<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <title>FoX_DoX</title>
  <link rel="stylesheet" type="text/css" href="DoX.css"/>
</head>
<body>
  <div class="DoX">
<a name="FoX"/>
<h1>FoX documentation.</h1>

<p><a href="FoX_DoX.html">All in one page</a></p>

<p><a href="FoX.html">Separate pages</a></p>

<h2>Introduction</h2>

<p>This document is the primary documentation for FoX, the Fortan/XML library. See below for <a href="#otherdoc">other sources of documentation</a>. It consists of:</p>

<p>Reference information on <a href="#Versioning">versions</a>, 
<a href="#Standards">standards compliance</a>,
and <a href="#Licensing">licensing</a>.</p>

<p>Information about how to <a href="#Compilation">get up and running with FoX</a>
and how to <a href="#Embedding">use FoX in an existing project</a>.</p>

<p>Finally, there is <a href="#apidoc">full API reference documentation</a>.</p>

<h2>Other documentation</h2>

<p><a name="otherdoc"/></p>

<p>This documentation is largely reference in nature. For new users it is best to start elsewhere:</p>

<h3>iFaX workshops</h3>

<p>Two workshops, entitled iFaX (Integrating Fortran and XML) have been run teaching the use of FoX, <a href="http://www.niees.ac.uk/events/ifax/index.shtml">one in January 2007</a>, and <a href="http://www.nesc.ac.uk/esi/events/841/">one in January 2008</a>. The full documentation and lectures from these may be found at:</p>

<ul>
<li><a href="http://buffalo.niees.group.cam.ac.uk/archive2.php?event_details=ifax">iFaX I</a></li>
<li><a href="http://www.nesc.ac.uk/action/esi/contribution.cfm?Title=841">iFaX II</a></li>
</ul>

<h3>Tutorials</h3>

<p>Out of the above workshops, some <a href="http://www1.gly.bris.ac.uk/~walker/FoX/iFaX">tutorial material</a> has been written, focussing on different use cases. Currently two are available:</p>

<ul>
<li><a href="http://www1.gly.bris.ac.uk/~walker/FoX/iFaX/iFaX.4/iFaX.4.html">SAX input</a></li>
<li><a href="http://www1.gly.bris.ac.uk/~walker/FoX/iFaX/iFaX.5/iFaX.5.html">DOM input</a></li>
</ul>

<p>There is also tutorial information on the use of WKML <a href="http://web.me.com/dove_family/xml/kml.html">here</a>.</p>

<h2>API documentation</h2>

<p><a name="apidoc"/></p>

<ul>
<li>FoX has seven sets of publically exported interfaces. These are documented here:</li>
</ul>

<h3>COMMON interfaces</h3>

<ul>
<li><a href="#FoX_common">FoX_common</a></li>
<li><a href="#FoX_utils">FoX_utils</a></li>
</ul>

<h3>OUTPUT interfaces</h3>

<ul>
<li><a href="#FoX_wxml">FoX_wxml</a></li>
<li><a href="#FoX_wcml">FoX_wcml</a></li>
<li><a href="#FoX_wkml">FoX_wkml</a></li>
</ul>

<h3>INPUT interface</h3>

<ul>
<li><a href="#FoX_sax">FoX_sax</a></li>
<li><a href="#FoX_dom">FoX_dom</a></li>
</ul>

<p>These documents describe all publically usable APIs.</p>

<p>Worked examples of the use of some of these APIs may be found in the <code>examples/</code> subdirectory, and tutorial-style documentaion is available from the links <a href="#otherdoc">above</a>.</p>

<h2>Other things</h2>

<ul>
<li><p><a href="#Debugging">Hints for debugging</a></p></li>
<li><p><a href="#Information">Further information</a></p></li>
</ul>
</div><hr/><div class="DoX">
<a name="Versioning"/>
<h1>FoX versioning</h1>

<p>This documentation describes version 4.1 of the FoX library.</p>

<p>This version includes output modules for general XML, and for CML; and a fully validating XML parser, exposed through a Fortran version of the SAX2 input parser and a Fortran mapping of the W3C DOM interface.</p>

<p>This is a stable branch, which will be maintained with important bugfixes.</p>

<p><a name="Changes"/></p>

<h2>FoX Changes</h2>

<p>As of FoX-3.0, there is one user-visible change that should be noted.</p>

<h3>Configuration/compilation</h3>

<p>In previous versions of FoX, the configure script was accessible as <code>config/configure</code>. Version 3.0 now follows common practice by placing the script in the main directory, so it is now called as <code>./configure</code>.</p>

<p>Previous versions of FoX made it quite hard to compile only portions of the library (eg only the CML output portion; or just the SAX input). This is now possible by specifying arguments to the configuration script. For example,</p>

<p><code>./configure --enable-wcml</code></p>

<p>will cause the generated Makefile to only compile the CML writing module and its dependencies.</p>

<p>See <a href="#Compilation">Compilation</a> for further details.</p>
</div><hr/><div class="DoX">
<a name="Compilation"/>
<h1>Configuration and compilation</h1>

<p>You will have received the FoX source code as a tar.gz file.</p>

<p>Unpack it as normal, and change directory into the top-level directory, FoX-$VERSION.</p>

<h3>Requirements for use</h3>

<p>FoX requires a Fortran 95 compiler - not just Fortran 90. All currently available versions of Fortran compilers claim to support F95. If your favoured compiler is not listed as working, I recommend the use of <a href="www.g95.org">g95</a>, which is free to download and use. And in such a case, please send a bug report to your compiler vendor.</p>

<p>In the event that you need to write a code targetted at multiple compilers, including some which have bugs preventing FoX compilation, please note the possibility of producing a <a href="#dummy_library">dummy library</a>.</p>

<h2>Configuration</h2>

<ul>
<li><p>In order to generate the Makefile, make sure that you have a Fortran compiler in your <code>PATH</code>, and do:</p>

<p><code>./configure</code></p></li>
</ul>

<p>This should suffice for most installations. However:</p>

<ol>
<li><p>You may not be interested in all of the modules that FoX supplies. For example, you may only be interested in output, not input. If so, you can select which modules you want using <code>--enable-MODULENAME</code> where MODULENAME is one of <code>wxml</code>, <code>wcml</code>, <code>wkml</code>, <code>sax</code>, <code>dom</code>. If none are explicitly enabled, then all will be built. (Alternatively, you can exclude modules one at a time with <code>--disable-MODULENAME</code>) Thus, for example, if you only care about CML output, and not anything else: <code>./configure --enable-wcml</code></p></li>
<li><p>If you have more than one Fortran compiler available, or it is not on your <code>PATH</code>, you can force the choice by doing:</p>

<p><code>./configure FC=/path/to/compiler/of/choice</code></p></li>
<li><p>It is possible that the configuration fails. In this case</p>

<ul>
<li>please tell me about it so I can fix it</li>
<li>all relevant compiler details are placed in the file arch.make; you may be able to edit that file to allow compilation. Again, if so, please let me know what you need to do.</li>
</ul></li>
<li><p>By default the resultant files are installed under the objs directory. If you wish them to be installed elsewhere, you may do</p>

<p><code>./configure --prefix=/path/to/installation</code></p></li>
</ol>

<p>Note that the configure process encodes the current directory location in several
places.  If you move the FoX directory later on, you will need to re-run configure.</p>

<ul>
<li><p>You may be interested in <a href="#dummy_library">dummy compilation</a>. This is activated with the <code>--enable-dummy</code> switch (but only works for wxml/wcml currently).</p>

<p><code>./configure --enable-wcml --enable-dummy</code></p></li>
</ul>

<h2>Compilation</h2>

<p>In order to compile the full library, now simply do:</p>

<pre><code>make
</code></pre>

<p>This will build all the requested FoX modules, and the relevant examples</p>

<h2>Testing</h2>

<p>In the full version of the FoX library, there are several testsuites included.</p>

<p>To run them all, simply run <code>make check</code> from the top-level directory. This will run the individual testsuites, and collate their results.</p>

<p>If any failures occur (unrelated to known compiler issues, see the <a href="http://github.com/andreww/fox/issues">up-to-date list</a>), please send a message to the mailing list (<a href="&#109;ai&#108;&#x74;&#x6F;:&#102;&#x6F;&#x78;&#x2D;&#x64;&#x69;&#x73;&#x63;&#117;s&#115;&#64;&#103;&#111;&#111;&#x67;&#x6C;&#101;&#103;&#114;&#111;u&#112;&#x73;&#46;&#x63;&#x6F;&#x6D;">&#102;&#x6F;&#x78;&#x2D;&#x64;&#x69;&#x73;&#x63;&#117;s&#115;&#64;&#103;&#111;&#111;&#x67;&#x6C;&#101;&#103;&#114;&#111;u&#112;&#x73;&#46;&#x63;&#x6F;&#x6D;</a>) with details of compiler, hardware platform, and the nature of the failure.</p>

<p>The testsuites for the SAX and DOM libraries are very extensive, and are somewhat fragile, so are not distributed with FoX. Please contact the author for details.</p>

<h2>Linking to an existing program</h2>

<ul>
<li>The files all having been compiled and installed, you need to link them into your program.</li>
</ul>

<p>A script is provided which will provide the appropriate compiler and linker flags for you; this will be created after configuration, in the top-level directory, and is called <code>FoX-config</code>. It may be taken from there and placed anywhere.</p>

<p>FoX-config takes the following arguments:</p>

<ul>
<li><code>--fcflags</code>: return flags for compilation</li>
<li><code>--libs</code>: return flags for linking</li>
<li><code>--wxml</code>: return flags for compiling/linking against wxml</li>
<li><code>--wcml</code>: return flags for compiling/linking against wcml</li>
<li><code>--sax</code>: return flags for compiling/linking against sax</li>
</ul>

<p>If it is called with no arguments, it will expand to compile &amp; link flags, thusly:</p>

<pre><code>f95 -o program program.f90 `FoX-config`
</code></pre>

<p>For compiling only against FoX, do the following:</p>

<pre><code>f95 -c `FoX-config --fcflags` sourcefile.f90
</code></pre>

<p>For linking only to the FoX library, do:</p>

<pre><code>f95 -o program `FoX-config --libs` *.o
</code></pre>

<p>or similar, according to your compilation scheme. </p>

<p>Note that by default, <code>FoX-config</code> assumes you are using all modules of the library. If you are only using part, then this can be specified by also passing the name of each module required, like so:</p>

<pre><code>FoX-config --fcflags --wcml
</code></pre>

<h2>Compiling a dummy library</h2>

<p><a name="dummy_library"/></p>

<p>Because of the shortcomings in some compilers, it is not possible to compile FoX everywhere. Equally, sometimes it is useful to be able to compile a code both with and without support for FoX (perhaps to reduce executable size). Especially where FoX is being used only for additional output, it is useful to be able to run the code and perform computations even without the possibility of XML output.</p>

<p>For this reason, it is possible to compile a dummy version of FoX. This includes all public interfaces, so that your code will compile and link correctly - however none of the subroutines do anything, so you can retain the same version of your code without having to comment out all FoX calls.</p>

<p>Because this dummy version of FoX contains nothing except empty subroutines, it compiles and links with all known Fortran 95 compilers, regardless of compiler bugs.</p>

<p>To compile the dummy code, use the <code>--enable-dummy</code> switch. Note that currently the dummy mode is not yet available for the DOM module.</p>

<h2>Alternative build methods</h2>

<p>The "-full" versions of FoX are also shipped with files
to help compile the code on using other systems using CMake
or from within Microsoft Visual Studio. Brief instructions for
using these files are below.</p>

<h3>CMake</h3>

<p>CMake does not build software itself but generates makefiles or
projectfiles (depending on the platform), that are then used to 
compile the software, it should thus be a cross platform 
method for building FoX (in theory at least).</p>

<p>Files needed for building FoX with CMake are included in the 
"-full" distribution. These can:</p>

<ul>
<li><p>do similar checks as current build tools to check for example how
ABORT and FLUSH work,
wether or not certain bugs in compilers are present,</p></li>
<li><p>compile FoX into static libraries.</p></li>
<li><p>generate Fortran files from m4 sources if m4 is present.</p></li>
<li><p>do out-of-source build, does not interfere with current build system</p></li>
<li><p>do a parallel build of fox (make -j)</p></li>
</ul>

<p>However, CMake cannot, at present, build the run the test suite or
the packaging scripts used for release. To build FoX with CMake 
the following is needed:</p>

<ul>
<li><p>CMake version >= 2.6.0</p></li>
<li><p>usual build tools: fortran compiler, make, ld, ...</p></li>
<li><p>m4 to generate fortran files from m4 sources (optional).</p></li>
</ul>

<p><strong>CMake Build instructions (linux):</strong> 
Once you installed cmake, go to the main directory of fox
and create a build directory, and from there, execute cmake thus:</p>

<pre><code>cd fox/

mkdir build/ &amp;&amp; cd build/

cmake ../

make -j
</code></pre>

<p>Libaries and module files can then be found in the subdirectories of build.</p>

<h3>Windows</h3>

<p>It is also possible to build FoX from within Microsoft Visual Studio
and the file FoX.vfproj contains a Visual Studio project for Intel Fortran
to simplify this process. At time of writing, it is compatible with 
Visual Studio 2011 and Intel Visual Fortran Composer XE 2011.</p>

<p>The project will build FoX in one of the four
 configurations: Win32/x64 and debug/release.
When building FoX for a specific configuration, 
an output library file Fox_debug.lib or Fox.lib 
and associated modules are created in a folder in 
a relative path  ../lib or ../libx64 respectively.</p>

<p>For a given configuration in in your application project
you will then need to:</p>

<ol>
<li><p>In "Fortran" "General" "Additional Include Directories" add 
the respective modules folder (generated above)</p></li>
<li><p>In "Linker" "General" "Additional library directories" add the 
path to the respective lib or libx64 folder.</p></li>
<li><p>In "Linker" "Input" "Additional dependencies" add Fox_debug.lib 
or FoX.lib respectively. </p></li>
</ol>

<p>Your application should now be able to build and link with FoX.</p>
</div><hr/><div class="DoX">
<a name="Embedding"/>
<h1>Using FoX in your own project.</h1>

<p>The recommended way to use FoX is to embed the full source code as a subdirectory, into an existing project.</p>

<p>In order to do this, you need to do something like the following:</p>

<ol>
<li>Put the full source code as a top-level subdirectory of the tree, called FoX.</li>
<li>Incorporate calls to FoX into the program.</li>
<li>Incorporate building FoX into your build process.</li>
</ol>

<h2>To incorporate into the program</h2>

<p>It is probably best to isolate use of XML facilities to a small part of the program. This is easily accomplished for XML input,
which will generally happen in only one or two places.</p>

<p>For XML output, this can be more complex. The easiest, and least intrusive way is probably to create a F90 module for your program, looking something like <code>example_xml_module.f90</code></p>

<p>Then you must somewhere (probably in your main program), use this module, and call <code>initialize_xml_output()</code> at the start; and then <code>end_xml_output()</code> at the end of the program.</p>

<p>In any of the subroutines where you want to output data to the xml file, you should then insert <code>use example_xml_module</code> at the beginning of the subroutine. You can then use any of the xml output routines with no further worries, as shown in the examples.</p>

<p>It is easy to make the use of FoX optional, by the use of preprocessor defines. This can be done simply by wrapping each call to your XML wrapper routines in <code>#ifdef XML</code>, or similar. Alternatively, the use of the dummy FoX interfaces allows you to switch FoX on and off at compile time - see <a href="#Compilation">Compilation</a>.</p>

<h2>To incorporate into the build process:</h2>

<h3>Configuration</h3>

<p>First, FoX must be configured, to ensure that it is set up correctly for your compiler.
(See <a href="#Compilation">Compilation</a>)
If your main code has a <code>configure</code> step, then run FoX's <code>configure</code> as part of it.</p>

<p>If your code doesn't have its own configure step, then the first thing that "make" does
should be to configure FoX, if it's not already configured. But that should only happen
once; every time you make your code thereafter, you don't need to re-configure FoX,
because nothing has changed. To do that, put a target like the following in your 
Makefile.</p>

<pre><code>FoX/.config:
        (cd FoX; ./configure FC=$(FC))
</code></pre>

<p>(Assuming that your <code>Makefile</code> already has a variable <code>FC</code> which sets the Fortran compiler)</p>

<p>When FoX configure completes, it "touch"es a file called <code>FoX/.config</code>. That means that
whenever you re-run your own make, it checks to see if <code>FoX/.config</code> exists - if it does,
then it knows FoX doesn't need to be re-configured, so it doesn't bother.</p>

<h3>Compilation of FoX</h3>

<p>Then, FoX needs to be compiled before your code (because your modules will depend
on FoX's modules.) But again, it only needs to be compiled once. You won't be changing
FoX, you'll only be changing your own code, so recompiling your code doesn't require
recompiling FoX.</p>

<p>So, add another target like the following;</p>

<pre><code>FoX/.FoX: FoX/.config
        (cd FoX; $(MAKE))
</code></pre>

<p>This has a dependency on the <code>configure</code> script as I showed above, but it will only run it 
if the <code>configure</code> script hasn't already been run.</p>

<p>When FoX is successfully compiled, the last thing its <code>Makefile</code> does is "touch" the file called
<code>FoX/.FoX</code>. So the above target checks to see if that file exists; and if it does, then it doesn't
bother recompiling FoX, because it's already compiled. On the very first time you compile
your code, it will <code>cd</code> into the FoX directory and compile it - but then never again.</p>

<p>You then need to have that rule be a dependency of your main target; like so:</p>

<pre><code>  MyExecutable: FoX/.FoX
</code></pre>

<p>(or whatever your default <code>Makefile</code> rule is).</p>

<p>which will ensure that before <code>MyExecutable</code> is compiled, <code>make</code> will check to see that FoX
has been compiled (which most of the time it will be, so nothing further will happen).
But the first time you compile your code, it will call the FoX target, and FoX will be
configured &amp; compiled.</p>

<h3>Compiling/linking your code</h3>

<p>You should add this to your <code>FFLAGS</code> (or equivalent - the variable that holds
flags for compile-time use.</p>

<pre><code>FFLAGS=-g -O2 -whatever-else $$(FoX/FoX-config --fcflags)
</code></pre>

<p>to make sure that you get the path to your modules. (Different compilers have different flags for specifying module
paths; some use <code>-I</code>, some use <code>-M</code>, <em>etc</em>, if you use the above
construction it will pick the right one automatically for your compiler.)</p>

<p>Similarly, for linking, add the following to your <code>LDFLAGS</code> (or equivalent - the variable
that holds flags for link-time use.)</p>

<pre><code>LDFLAGS=-lwhatever $$(FoX/FoX-config --libs)
</code></pre>

<p>(For full details of the <code>FoX-config</code> script, see <a href="#Compilation">Compilation</a>)</p>

<h3>Cleaning up</h3>

<p>Finally - you probably have a <code>clean</code> target in your makefile. Don't tie FoX into this
target - most of the time when you <code>make clean</code>, you don't want to <code>make clean</code> with 
FoX as well, because there's no need - FoX won't have changed and
it'll take a couple of minutes to recompile.</p>

<p>However, you can add a <code>distclean</code> (or something) target, which you use before
moving your code to another machine, that looks like:</p>

<pre><code>distclean: clean
        (cd FoX; $(MAKE) distclean)
</code></pre>

<p>and that will ensure that when you do <code>make distclean</code>, even FoX's object files are
cleaned up. But of course that will mean that you have to reconfigure &amp; recompile
FoX next time you compile your code</p>
</div><hr/><div class="DoX">
<a name="Standards"/>
<h1>Standards compliance</h1>

<p>FoX is written with reference to the following standards:</p>

<p>[XML10]: <a href="http://www.w3.org/TR/REC-xml/">http://www.w3.org/TR/REC-xml/</a></p>

<p>[XML11]: <a href="http://www.w3.org/TR/xml11">http://www.w3.org/TR/xml11</a></p>

<p>[Namespaces10]: <a href="http://www.w3.org/TR/xml-names">http://www.w3.org/TR/xml-names</a></p>

<p>[Namespaces11]: <a href="http://www.w3.org/TR/xml-names11">http://www.w3.org/TR/xml-names11</a></p>

<p>[xml:id]: <a href="http://www.w3.org/TR/xml-id/">http://www.w3.org/TR/xml-id/</a></p>

<p>[xml:base]: <a href="http://www.w3.org/TR/xmlbase/">http://www.w3.org/TR/xmlbase/</a></p>

<p>[CanonicalXML]: <a href="http://www.w3.org/TR/xml-c14n">http://www.w3.org/TR/xml-c14n</a></p>

<p>[SAX2]: <a href="http://saxproject.org">http://saxproject.org</a></p>

<p>[DOM1]:  <a href="http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html">http://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html</a></p>

<p>[DOM2]:  <a href="http://www.w3.org/TR/DOM-Level-2-Core/">http://www.w3.org/TR/DOM-Level-2-Core/</a></p>

<p>[DOM3]:  <a href="http://www.w3.org/TR/DOM-Level-3-Core/">http://www.w3.org/TR/DOM-Level-3-Core/</a></p>

<p>In particular:</p>

<ul>
<li><p><code>FoX_wxml</code> knows about [XML10], [XML11], [Namespaces10], [Namespaces11], [CanonicalXML]</p></li>
<li><p><code>FoX_sax</code> knows about  [XML10], [XML11], [Namespaces10], [Namespaces11], [xml:id], [xml:base], [SAX2]</p></li>
<li><p><code>FoX_dom</code> knows about [XML10], [XML11], [Namespaces10], [Namespaces11], [xml:id], [xml:base], [DOM1], [DOM2], [DOM3], [CanonicalXML]</p></li>
</ul>

<p>For exceptions, please see the relevant parts of the FoX documentation.</p>
</div><hr/><div class="DoX">
<a name="FoX_common"/>
<h1>FoX_common</h1>

<p>FoX_common is a module exporting interfaces to a set of convenience functions common to all of the FoX modules, which are of more general use.</p>

<p>Currently, there are three publically available functions and four subroutines:</p>

<ul>
<li>The subroutine <code>str</code> converts primitive datatypes into strings in a consistent fashion, conformant with the expectations of XML processors.</li>
</ul>

<p>It is fully described in <a href="#StringFormatting">StringFormatting</a></p>

<ul>
<li><p>The subroutine <code>rts</code> performs the reverse function, taking a string (obtained from an XML document) and converts it into a primitive Fortran datatype.</p></li>
<li><p>The function <code>countrts</code> examinies a string and determines the size of array requiered to hold all its data, once converted to a primitive Fortran datatype.</p></li>
</ul>

<p>It is fully described in <a href="#StringConversion">StringConversion</a></p>

<p>The final four procedures change the way that errors and warnings are handled when encounterd by any FoX modules. Using these procedures it is possible to convert non-fatal warnings and fatal errors to calls to the internal about routine. This generally has the effect of generating a stack trace or core dump of the program before temination. This is a global setting for all XML documents being manipulated. Two subroutines take a single logical argument to turn on (true) and off (false) the feature for warnings and errors respectivly:</p>

<ul>
<li><p><code>FoX_set_fatal_warnings</code> for warnings </p></li>
<li><p><code>FoX_set_fatal_errors</code> for errors</p></li>
</ul>

<p>and two functions (without arguments) allow the state to be checked:</p>

<ul>
<li><p><code>FoX_get_fatal_warnings</code> for warnings</p></li>
<li><p><code>FoX_get_fatal_errors</code> for errors</p></li>
</ul>

<p>Both fatal warnings and errors are off by default. This corresponds to the previous behaviour. </p>
</div><hr/><div class="DoX">
<a name="StringFormatting"/>
<h1>String handling in FoX</h1>

<p>Many of the routines in wxml, and indeed in wcml which is built on top of wxml, are overloaded so that data may be passed to the same routine as string, integer, logical, real, or complex data.</p>

<p>In such cases, a few notes on the conversion of non-textual data to text is in order. The
standard Fortran I/O formatting routines do not offer the control required for useful XML output, so FoX performs all its own formatting.</p>

<p>This formatting is done internally through a function which is also available publically to the user, <code>str</code>.</p>

<p>To use this in your program, import it via:</p>

<pre><code>use FoX_common, only; str
</code></pre>

<p>and use it like so:</p>

<pre><code> print*, str(data)
</code></pre>

<p>In addition, for ease of use, the <code>//</code> concatenation operator is overloaded, such that strings can easily be formed by concatenation of strings to other datatypes. To use this you must import it via:</p>

<pre><code> use FoX_common, only: operator(//)
</code></pre>

<p>and use it like so:</p>

<pre><code> integer :: data
 print*, "This is a number "//data
</code></pre>

<p>This will work for all native Fortran data types - but no floating point formatting is available as described below with concatenation, only with str()</p>

<p>You may pass data of the following primitive types to <code>str</code>:</p>

<h2>Scalar data</h2>

<h3>Character (default kind)</h3>

<p>Character data is returned unchanged.</p>

<h3>Logical (default kind)</h3>

<p>Logical data is output such that True values are converted to the string 'true', and False to the string 'false'.</p>

<h3>Integer (default kind)</h3>

<p>Integer data is converted to the standard decimal representation.</p>

<h3>Real numbers (single and double precision)</h3>

<p>Real numbers, both single and double precision, are converted to strings in one of two ways, with some control offered to the user. The output will conform to the real number formats specified by XML Schema Datatypes.</p>

<p>This may be done in one of two ways:</p>

<ol>
<li><p>Exponential notation, with variable number of significant figures. Format strings of the form "<code>s</code><strong>n</strong>"  are accepted, where <strong>n</strong> is the number of significant figures.</p>

<p>Thus the number <code>111</code>, when output with various formats, will produce the following output:</p></li>
</ol>

<table class="format">
<tr>
  <td class="format"> s1 </td><td> 1e2 </td>
</tr><tr>
  <td> s2 </td><td> 1.1e2 </td>
</tr><tr>
  <td> s3 </td><td> 1.11e2 </td>
</tr><tr>
  <td> s4 </td><td> 1.110e2 </td>
</tr>
</table>

<p>The number of significant figures should lie between 1 and the number of digits precision provided by the real kind. If a larger or smaller number is specified, output will be truncated accordingly. If unspecified, then a sensible default will be chosen.</p>

<p>This format is not permitted by XML Schema Datatypes 1.0, though it is in 2.0</p>

<ol>
<li><p>Non-exponential notation, with variable number of digits after the decimal point. Format strings of the form "<code>r</code><strong>n</strong>", where <strong>n</strong> is the number of digits after the decimal point.</p>

<p>Thus the number <code>3.14159</code>, when output with various formats, will produce the following output:</p></li>
</ol>

<table class="format">
<tr>
  <td> r0 </td><td> 3 </td>
</tr><tr>
  <td> r1 </td><td> 3.1</td>
</tr><tr>
  <td> r2 </td><td> 3.14</td>
</tr><tr>
  <td> r3 </td><td> 3.142 </td>
</tr>
</table>

<p>The number of decimal places must lie between 0 and whatever would output the maximum digits precision for that real kind.  If a larger or smaller number is specified, output will be truncated accorsingly. If unspecified, then a sensible default will be chosen.</p>

<p>This format is the only one permitted by XML Schema Datatypes 1.0</p>

<p>If no format is specified, then a default of exponential notation will be used.</p>

<p>If a format is specified not conforming to either of the two forms above, a run-time error will be generated.</p>

<p><strong>NB</strong> Since by using FoX or str, you are passing real numbers through various functions, this means that
       they must be valid real numbers. A corollary of this is that if you pass in +/-Infinity, or NaN, then
       the behaviour of FoX is unpredictable, and may well result in a crash. This is a consequence of the
       Fortran standard, which strictly disallows doing anything at all with such numbers, including even
       just passing them to a subroutine.</p>

<h2>Complex numbers (single and double precision)</h2>

<p>Complex numbers will be output as pairs of real numbers, in the following way:</p>

<p><code>(1.0e0)+i(1.0e0)</code></p>

<p>where the two halves can be formatted in the way described for 'Real numbers' above; only one format may be specified, and it will apply to both.</p>

<p>All the caveats described above apply for complex number as well; that is, output of complex numbers either of whose components are infinite or NaN is illegal in Fortran, and more than likely will cause a crash in FoX.</p>

<h2>Arrays and matrices</h2>

<p>All of the above types of data may be passed in as arrays and matrices as well. In this case, a string containing all the individual elements will be returned, ordered as they would be in memory, each element separated by a single space.</p>

<p>If the data is character data, then there is an additional option to str, <code>delimiter</code> which may be any single-character string, and will replace a space as the delimiter.</p>

<h2>wxml/wcml wrappers.</h2>

<p>All functions in wxml which can accept arbitrary data (roughly, wherever you put anything that is not an XML name; attribute values, pseudo-attribute values, character data) will take scalars, arrays, and matrices of any of the above data types, with <code>fmt=</code> and <code>delimiter=</code> optional arguments where appropriate.</p>

<p>Similarly, wcml functions which can accept varied data will behave similarly.</p>
</div><hr/><div class="DoX">
<a name="StringConversion"/>
<h1>String conversion</h1>

<p>Two procedures are provided to simplify reading data retreved from XML documents into Fortran variables. The subroutine <code>rts</code> performs the data conversion step and the function <code>countrts</code> can be used to allocate an array of the correct size for the incomming data. </p>

<h2><code>rts</code> subroutine</h2>

<p>The <code>rts</code> subroutine can be imported from <code>FoX_common</code>. In its simplest form, it is called in this fashion:</p>

<pre><code>call rts(string, data)
</code></pre>

<p><code>string</code> is a simple Fortran string (probably retrieved from an XML file.)</p>

<p><code>data</code> is any native Fortran datatype: <code>logical</code>, <code>character</code>, <code>integer</code>, <code>real</code>, <code>double precision</code>, <code>complex</code>, <code>double complex</code>, and may be a scalar, 1D or 2D array.</p>

<p><code>rts</code> will attempt to parse the contents of <code>string</code> into the appropriate datatype, and return the value in <code>data</code>.</p>

<p>Additional information or error handling is accomplished with the following optional arguments:</p>

<h3><code>num</code></h3>

<p><code>num</code> is an integer; on returning from the function it indicates the number of data items read before either:</p>

<ul>
<li>an error occurred</li>
<li>the string was exhausted of data items  </li>
<li><code>data</code> was filled.</li>
</ul>

<h3><code>iostat</code></h3>

<p><code>iostat</code> is an integer, which on return from the function has the values:</p>

<ul>
<li><code>0</code> for no problems</li>
<li><code>-1</code> if too few elements were found in <code>string</code> to fill up <code>data</code></li>
<li><code>1</code> if <code>data</code> was filled, but there were still data items left in <code>string</code></li>
<li><code>2</code> if the characters found in <code>string</code> could not be converted to the appropriate type for <code>data</code>.</li>
</ul>

<p>NB if <code>iostat</code> is not specified, and a non-zero value is returned, then the program will stop with an error message.</p>

<h2>String formatting</h2>

<p>When <code>string</code> is expected to be an array of strings, the following options are used to break <code>string</code> into its constituent elements:</p>

<ul>
<li><p>By default it is assumed that the elements are separated by whitespace, and that multiple whitespace characters are not significant. No zero-length elements are possible, nor are elements containing whitespace.</p></li>
<li><p>An optional argument, <code>separator</code> may be specified, which is a single character. In this case, each element consists of all characters between subsequent occurences of the <code>separator</code>. Zero-length elements are possible, but no escaping mechanism is possible.</p></li>
<li><p>Alternatively, an optional logical argument <code>csv</code> may be specified. In this case, the value of <code>delimiter</code> is ignored, and the string is parsed as a Comma-Separated-Value string, according to <a href="http://tools.ietf.org/html/rfc4180">RFC 4180</a>.</p></li>
</ul>

<h2>Numerical formatting.</h2>

<p>Numbers are expected to be formatted according to the usual conventions for Fortran input.</p>

<h2>Complex number formatting.</h2>

<p>Complex numbers may be formatted according to either normal Fortran conventions (comma-separated pairs) or <a href="http://cmlcomp.org/t/wiki/FpxStandard">CMLComp conventions</a></p>

<h2>Logical variable formatting.</h2>

<p>Logical variables must be encoded according to the conventions of <a href="http://www.w3.org/TR/xmlschema-2/#boolean">XML Schema Datatypes</a>  - that is, True may be written as "true" or "1", and False may be written as "false" or "0".</p>

<h2><code>countrts</code> function</h2>

<p>The <code>countrts</code> function can also be imported from <code>FoX_common</code>. In its simplest form, it is called in this fashion:</p>

<pre><code>countrts(string, datatype)
</code></pre>

<p><code>string</code> is a simple Fortran string (probably retrived from an XML file)</p>

<p><code>datatype</code> is a scalar argument of any native Fortran datatype (<code>logical</code>, <code>character</code>, <code>integer</code>, <code>real</code>, <code>double precision</code>, <code>complex</code> or <code>double complex</code>).</p>

<p>The function returns a default integer equal to the number of elements that rts would
return if called with a sufficently large array of the same type as <code>datatype</code>. <code>countrts</code> returns 0 to indicate that characters were found in the string that could not be converted. If datatype is a character, the optional arguments <code>seperator</code> and <code>csv</code> are avalable as described in "string formatting" above. The <code>countrts</code> function is pure and can be used as a specification function.</p>
</div><hr/><div class="DoX">
<a name="FoX_wxml"/>
<h1>WXML</h1>

<p><code>wxml</code> is a general Fortran XML output library. It offers a Fortran interface, in the form of a number of subroutines,  to generate well-formed XML documents. Almost all of the XML features described in <a href="#XML11">XML11</a>  and <a href="#Namespaces">Namespaces</a> are available, and <code>wxml</code> will diagnose almost all attempts to produce an invalid document. <a href="#Exceptions">Exceptions</a> below describes where <code>wxml</code> falls short of these aims.</p>

<p>First, <a href="#Conventions">Conventions</a> describes the conventions use in this document.</p>

<p>Then, <a href="#Functions">Functions</a> lists all of <code>wxml</code>'s publically exported functions, in three sections:</p>

<ol>
<li><a href="#simple">Firstly</a>, the very few functions necessary to create the simplest XML document, containing only elements, attributes, and text. </li>
<li><a href="#NSfunctions">Secondly</a>, those functions concerned with XML Namespaces, and how Namespaces affect the behaviour of the first tranche of functions.  </li>
<li><a href="#obscure">Thirdly</a>, a set of more rarely used functions required to access some of the more esoteric corners of the XML specification.</li>
</ol>

<p>Please note that where the documentation below is not clear, it may be useful to look at some of the example files. There is a very simple example in the <code>examples/</code> subdirectory, but which nevertheless shows the use of most of the features you will use.</p>

<p>A more elaborate example, using almost all of the XML features found here, is available in the top-level directory as <code>wxml_example.f90</code>. It will be automatically compiled as part of the build porcess.</p>

<p><a name="Conventions"/></p>

<h2>Conventions and notes:</h2>

<h4>Conventions used below.</h4>

<ul>
<li>Function names are in <code>monospace</code></li>
<li>argument names are in <strong>bold</strong></li>
<li>optional argument names are in (<strong>parenthesized bold</strong>)</li>
<li>argument types are in <em>italic</em> and may consist of:</li>
<li><em>string</em>: string of arbitrary (unless otherwise specified) length</li>
<li><em>integer</em>: default integer</li>
<li><em>real(sp)</em>: single precision real number</li>
<li><em>real(dp)</em>: double precision real number</li>
<li><em>logical</em>: default logical </li>
<li><em>real</em>: either of <em>real(sp)</em> or <em>real(dp)</em></li>
<li><em>anytype</em>: any of <em>logical</em>, <em>integer</em>, <em>real(sp)</em>, <em>real(dp)</em>, <em>string</em></li>
</ul>

<p>Note that where <em>strings</em> are passed in, they will be passed through entirely unchanged to the output file - no truncation of whitespace will occur.</p>

<p>It is strongly recommended that the functions be used with keyword arguments rather than replying on implicit ordering.</p>

<h4>Derived type: <code>xmlf_t</code></h4>

<p>This is an opaque type representing the XML file handle. Each function requires this as an argument, so it knows which file to operate on. (And it is an output of the xml_OpenFile subroutine) Since all subroutines require it, it is not mentioned below.</p>

<p><a name="Functions"/></p>

<h2>Function listing</h2>

<p><a name="simple"/></p>

<h3>Frequently used functions</h3>

<ul>
<li><code>xml_OpenFile</code> <br />
<strong>filename</strong>: <em>string</em>: Filename to be opened <br />
<strong>xf</strong>: <em>xmlf_t</em>: XML File handle <br />
(<strong>channel</strong>): <em>integer</em>: What Fortran file handle should the XML file be attached to? 
<em>default: picked by the library at runtime</em> <br />
(<strong>pretty_print</strong>): <em>logical</em>: Should the XML output be formatted to look pretty? (This implies that whitespace is not significant) 
<em>default: false</em> <br />
(<strong>replace</strong>): <em>logical</em>: Should the file be replaced if it already exists? 
<em>default: no, stop at runtime if file already exists</em> <br />
(<strong>addDecl</strong>): <em>logical</em>: Should an XML declaration be added at the start of the file? 
<em>default: yes</em> <br />
(<strong>namespace</strong>): <em>logical</em>: Should wxml prevent the output of namespace-ill-formed documents? 
<em>default: yes</em> <br />
(<strong>validate</strong>): <em>logical</em>: Should wxml carry out any checks on the optional VC constraints specified by XML? 
<em>default: no</em> <br />
(<strong>warning</strong>): <em>logical</em>: Should wxml emit warnings when it is unable to guarantee well-formedness? 
<em>default: no</em>  </li>
</ul>

<p>Open a file for writing XML</p>

<p>By default, the XML will have no extraneous text nodes. This can have the effect of it
looking slightly ugly, since there will be no newlines inserted between tags.</p>

<p>This behaviour can be changed to produce slightly nicer looking XML, by switching
on pretty_print. This will insert newlines and spaces between some tags where
they are unlikely to carry semantics. Note, though, that this does result in 
the XML produced being not quite what was asked for, since extra characters and
text nodes have been inserted.</p>

<p>NB: The <strong>replace</strong> option should be noted. By default, xml_OpenFile will fail with a runtime error if you try and write to an existing file. If you are sure you want to continue on in such a case, then you can specify <code>**replace**=.true.</code> and any existing files will be overwritten. If finer granularity is required over how to proceed in such cases, use the Fortran <code>inquire</code> statement in your code. There is no 'append' functionality by design - any XML file created by appending to an existing file would be invalid.</p>

<ul>
<li><code>xml_Close</code> <br />
<strong>xf</strong>: <em>xmlf_t</em>: XML File handle
(<strong>empty</strong>): Can the file be empty? <em>default: .false.</em></li>
</ul>

<p>Close an opened XML file, closing all still-opened tags so that it is well-formed.</p>

<p>In the normal run of event, trying to close an XML file with no root element will cause an error, since this is not well-formed. However, an optional argument, <strong>empty</strong> is provided in case it is desirable to close files which may be empty. In this case, a warning will still be emitted, but no fatal error generated.</p>

<ul>
<li><code>xml_NewElement</code> <br />
<strong>name</strong>: <em>string</em>:
Name of tag (for namespaced output, you need to include the prefix)</li>
</ul>

<p>Open a new element tag</p>

<ul>
<li><code>xml_EndElement</code> <br />
<strong>name</strong>: <em>string</em>: 
Name of tag to be closed (if it doesn't match currently open tag, you'll get an error)</li>
</ul>

<p>Close an open tag</p>

<ul>
<li><code>xml_AddAttribute</code> <br />
<strong>name</strong>: <em>string</em>: Name of attribute <br />
<strong>value</strong>: <em>anytype</em>: Value of attribute <br />
(<strong>escape</strong>): <em>logical</em>: if the attribute value is a string, should the attribute value be escaped?
<em>default: true</em> <br />
(<strong>type</strong>): <em>string</em>: the type of the attribute. This must be one of <code>CDATA</code>, <code>ID</code>, <code>IDREF</code>, <code>IDREFS</code>, <code>NMTOKEN</code>, <code>NMTOKENS</code>, <code>ENTITY</code>, <code>ENTITIES</code>, or <code>NOTATION</code> (always upper case). If specified, this must match any attribute declarations that have been previously declared in the DTD. If unspecified this (as the XML standard requires) defaults to <code>CDATA</code>.</li>
</ul>

<p>Add an attribute to the currently open tag.</p>

<p>By default, if the attribute value contains markup characters, they will be escaped automatically by
wxml before output.</p>

<p>However, in rare cases you may not wish this to happen - if you wish to output Unicode
characters, or entity references. In this case, you should set <code>escape=.false.</code> for the relevant
subroutine call. Note that if you do this, no checking on the validity of the output string iis performed; the onus is on you to ensure well-formedness</p>

<p>The value to be added may be of any type; it will be converted to text according to FoX's <a href="str.html">formatting rules</a>,
and if it is a 1- or 2-dimensional array, the elements will all be output, separated by spaces (except if it is a character array, in which
case the delimiter may be changed to any other single character using an optional argument).</p>

<p>NB The <strong>type</strong> option is only provided so that in the case of an external DTD which FoX is unaware of, the attribute type can be specified (which gives FoX more information to ensure well-formedness and validity). Specifying the type incorrectly may result in spurious error messages)</p>

<ul>
<li><code>xml_AddCharacters</code> <br />
<strong>chars</strong> <em>anytype</em>:
The text to be output <br />
(<strong>parsed</strong>): <em>logical</em>: Should the output characters be parsed (ie should the library replace '&amp;' with '&amp;' etc?) or unparsed (in which case
the characters will be surrounded by CDATA tags.
<em>default: yes</em> <br />
(<strong>delimiter</strong>): <em>character(1)</em>: If <strong>data</strong> is a character array, what should the delimiter between elements be on output?
<em>default: a single space</em> <br />
(<strong>ws_significant</strong>): <em>logical</em>: Is any whitespace in the string significant? <em>default: unknown</em></li>
</ul>

<p>Add text data. The data to be added may be of any type; they will be converted to text according to FoX's <a href="str.html">formatting rules</a>,
and if they are a 1- or 2-dimensional array, the elements will all be output, separated by spaces (except if it is a character array, in which
case the delimiter may be changed to any other single character using an optional argument).</p>

<ul>
<li><code>xml_AddNewline</code></li>
</ul>

<p>Within the context of character output, add a (system-dependent) newline character. This function can only
be called wherever <code>xml_AddCharacters</code> can be called. (Newlines outside of character context are under
FoX's control, and cannot be manipulated by the user.)</p>

<p><a name="NSfunctions"/></p>

<h3>Namespace-aware functions:</h3>

<ul>
<li><code>xml_DeclareNamespace</code> <br />
<strong>nsURI</strong> <em>string</em>: The URI of the namespace <br />
(<strong>prefix</strong>) <em>string</em>: The namespace prefix to be used in the document. If absent, then the default namespace is affected.</li>
</ul>

<p>Add an XML Namespace declaration. This function may be called at any time, and its precise effect depends on when it is called; see below</p>

<ul>
<li><code>xml_UndeclareNamespace</code> <br />
(<strong>prefix</strong>) <em>string</em>: The namespace prefix to be used in the document. If absent, then the default namespace is affected.</li>
</ul>

<p>Undeclare an XML namespace. This is equivalent to declaring an namespace with an empty URI, and renders the namespace ineffective for the scope of the declaration. For explanation of its scope, see below.</p>

<p><strong>NB</strong> Use of <code>xml_UndeclareNamespace</code> implies that the resultant document will be compliant with XML Namespaces 1.1, but not 1.0; wxml will issue an error when trying to undeclare namespaces under XML 1.0.</p>

<h4>Scope of namespace functions</h4>

<p>If  <code>xml_[Un]declareNamespace</code> is called immediately prior to an <code>xml_NewElement</code> call, then the namespace will be declared in that next element, and will therefore take effect in all child elements.</p>

<p>If it is called prior to an <code>xml_NewElement</code> call, but that element has namespaced attributes </p>

<p>To explain by means of example: In order to generate the following XML output:</p>

<pre><code> &lt;cml:cml xmlns:cml="http://www.xml-cml.org/schema"/&gt;
</code></pre>

<p>then the following two calls are necessary, in the prescribed order:</p>

<pre><code>  xml_DeclareNamespace(xf, 'cml', 'http://www.xml-cml.org')
  xml_NewElement(xf, 'cml:cml')
</code></pre>

<p>However, to generate XML input like so:
      <cml xhtml:class="symbol" xmlns:xhtml="http://www.w3.org/1999/xhtml"/>
that is, where the namespace refers to an attribute at the same level,
then as long as the <code>xml_DeclareNamespace</code> call is made before the element tag is closed (either by <code>xml_EndElement</code>, or by a new element tag being opened, or some text being added etc.) the correct XML will be generated.</p>

<p>Two previously mentioned functions are affected when used in a namespace-aware fashion.</p>

<ul>
<li><code>xml_NewElement</code>, <code>xml_AddAttribute</code></li>
</ul>

<p>The element or attribute name is checked, and if it is a QName (ie if it is of the form prefix:tagName) then wxml will check that prefix is a
registered namespace prefix, and generate an error if not.</p>

<p><a name="obscure"/></p>

<h3>More rarely used functions:</h3>

<p>If you don't know the purpose of any of these, then you don't need to. </p>

<ul>
<li><code>xml_AddXMLDeclaration</code> <br />
(<strong>version</strong>) <em>string</em>: XML version to be used.
<em>default: 1.0</em> <br />
(<strong>encoding</strong>) <em>string</em>: character encoding of the document
<em>default: absent</em> <br />
(<strong>standalone</strong>) <em>logical</em>: is this document standalone?
<em>default: absent</em>  </li>
</ul>

<p>Add XML declaration to the first line of output. If used, then the file must have been opened with <code>addDecl = .false.</code>, and this must be the first wxml call to the document.o</p>

<p>NB The only XML versions available are 1.0 and 1.1. Attempting to specify anything else will result in an error. Specifying version 1.0 results in additional output checks to ensure the resultant document is XML-1.0-conformant.</p>

<p>NB Note that if the encoding is specified, and is specified to not be UTF-8, then if the specified encoding does not match that supported by the Fortran processor, you may end up with output you do not expect.</p>

<ul>
<li><code>xml_AddDOCTYPE</code> <br />
<strong>name</strong> <em>string</em>: DOCTYPE name <br />
(<strong>system</strong>) <em>string</em>: DOCTYPE SYSTEM ID <br />
(<strong>public</strong>) <em>string</em>: DOCTYPE PUBLIC ID  </li>
</ul>

<p>Add an XML document type declaration. If used, this must be used prior to first <code>xml_NewElement</code> call, and only one such call must be made.</p>

<ul>
<li><code>xml_AddInternalEntity</code> <br />
<strong>name</strong> <em>string</em>: name of internal entity <br />
<strong>value</strong> <em>string</em>: value of internal entity  </li>
</ul>

<p>Define an internal entity for the document. If used, this call must be made after <code>xml_AddDOCTYPE</code> and before the first <code>xml_NewElement</code> call.</p>

<ul>
<li><code>xml_AddExternalEntity</code> <br />
<strong>name</strong> <em>string</em>: name of external entity <br />
<strong>system</strong> <em>string</em>: SYSTEM ID of external entity <br />
(<strong>public</strong>) <em>string</em>: PUBLIC ID of external entity
<em>default: absent</em> <br />
(<strong>notation</strong>) <em>string</em>: notation for external entity
<em>default: absent</em>  </li>
</ul>

<p>Define an external entity for the document. If used, this call must be made after <code>xml_AddDOCTYPE</code> and before the first <code>xml_NewElement</code> call.</p>

<ul>
<li><code>xml_AddParameterEntity</code> <br />
<strong>name</strong> <em>string</em>: name of parameter entity <br />
(<strong>PEdef</strong>) <em>string</em>: definition of parameter entity
<em>default: absent</em> <br />
(<strong>system</strong>) <em>string</em>: SYSTEM ID of parameter entity
<em>default: absent</em> <br />
(<strong>public</strong>) <em>string</em>: PUBLIC ID of parameter entity
<em>default: absent</em>  </li>
</ul>

<p>Define a parameter entity for the document. If used, this call must be made after <code>xml_AddDOCTYPE</code> and before the first <code>xml_NewElement</code> call.</p>

<ul>
<li><code>xml_AddNotation</code> <br />
<strong>name</strong> <em>string</em>: name of notation <br />
(<strong>system</strong>) <em>string</em>: SYSTEM ID of notation
<em>default: absent</em> <br />
(<strong>public</strong>) <em>string</em>: PUBLIC ID of notation
<em>default: absent</em>  </li>
</ul>

<p>Define a notation for the document. If used, this call must be made after <code>xml_AddDOCTYPE</code> and before the first <code>xml_NewElement</code> call.</p>

<ul>
<li><code>xml_AddElementToDTD</code> <br />
<strong>name</strong> <em>string</em>: name of element <br />
<strong>declaration</strong> <em>string</em>: declaration of element  </li>
</ul>

<p>Add an ELEMENT declaration to the DTD. The syntax of the declaration is not checked in any way, nor does this affect how elements may be added in the content of the XML document.</p>

<p>If used, this call must be made after <code>xml_AddDOCTYPE</code> and before the first <code>xml_NewElement</code> call.</p>

<ul>
<li><code>xml_AddAttlistToDTD</code> <br />
<strong>name</strong> <em>string</em>: name of element <br />
<strong>declaration</strong> <em>string</em>: declaration of element  </li>
</ul>

<p>Add an ATTLIST declaration to the DTD. The syntax of the declaration is not checked in any way, nor does this affect how attributes may be added in the content of the XML document.</p>

<p>If used, this call must be made after <code>xml_AddDOCTYPE</code> and before the first <code>xml_NewElement</code> call.</p>

<ul>
<li><code>xml_AddPEreferenceToDTD</code> <br />
<strong>name</strong> <em>string</em>: name of PEreference</li>
</ul>

<p>Add a reference to a Parameter Entity in the DTD. No check is made according to whether the PE exists, has been declared, or may legally be used.</p>

<p>If used, this call must be made after <code>xml_AddDOCTYPE</code> and before the first <code>xml_NewElement</code> call.</p>

<ul>
<li><code>xml_AddXMLStylesheet</code> <br />
<strong>href</strong> :<em>string</em>: 
address of stylesheet <br />
<strong>type</strong>: <em>string</em>:
type of stylesheet (generally "text/xsl") <br />
(<strong>title</strong>): <em>string</em>:
title of stylesheet
<em>default: none</em> <br />
(<strong>media</strong>): <em>string:</em>
output media type
<em>default: none</em> <br />
(<strong>charset</strong>): <em>string</em>
charset of media type
<em>default:none</em> <br />
(<strong>alternate</strong>): <em>string</em>:
alternate
<em>default:none</em>  </li>
</ul>

<p>Add XML stylesheet processing instruction, as described in [Stylesheets]. If used, this call must be made before the first <code>xml_NewElement</code> call.</p>

<ul>
<li><code>xml_AddXMLPI</code> <br />
<strong>name</strong>: <em>string</em>:
name of PI <br />
(<strong>data</strong>): <em>string</em>:
data for PI <br />
(<strong>xml</strong>): <em>logical</em>: (see below)
<em>default: false</em> <br />
(<strong>ws_significant</strong>): <em>logical</em>: if this is a PI containing only <strong>data</strong>, then is any whitespace in the data significant? <em>default: unknown</em></li>
</ul>

<p>Add an XML Processing Instruction.</p>

<p>If data is present, nothing further can be added to the PI. If it is <em>not</em> present, then pseudoattributes may be added using the call below.
Normally, the <strong>name</strong> is checked to ensure that it is XML-compliant. This requires that PI targets not start with <code>[Xx][Mm][Ll]</code>, because such names are reserved. However, some are defined by later W3 specificataions. If you wish to use such PI targets, then set <code>xml=.true.</code> when outputting them.</p>

<p>The output PI will look like:
<code>&lt;?name data?&gt;</code></p>

<ul>
<li><code>xml_AddPseudoAttribute</code> <br />
<strong>name</strong>: <em>string</em>:
Name of pseudoattribute <br />
<strong>value</strong>: <em>anytype</em>:
Value of pseudoattribute
(<strong>ws_significant</strong>): <em>logical</em>: If there is any whitespace in the value of this pseudoattribute, is is significant?</li>
</ul>

<p>Add a pseudoattribute to the currently open PI.</p>

<ul>
<li><code>xml_AddComment</code> <br />
<strong>comment</strong>: <em>string</em>
Contents of comment <br />
(<strong>ws_significant</strong>): <em>logical</em>: is any whitespace in the comment string significant? <em>default: unknown</em></li>
</ul>

<p>Add an XML comment.</p>

<ul>
<li><code>xml_AddEntityReference</code> <br />
<strong>entityref</strong>: Entity reference.</li>
</ul>

<p>This may be used anywhere that <code>xml_AddCharacters</code> may be, and will insert an entity reference into the contents of the XML document at that point. Note that if the entity inserted is a character entity, its validity well be checked according to the rules of XML-1.1, not 1.0.</p>

<p>If the entity reference is not a character entity, then no check is made of its validity, and a warning will be issued</p>

<h3>Functions to query XML file objects</h3>

<p>These functions may be of use in building wrapper libraries:</p>

<ul>
<li><code>xmlf_Name</code> result(<em>string</em>)</li>
</ul>

<p>Return the filename of an open XML file</p>

<ul>
<li><code>xmlf_OpenTag</code> result(<em>string</em>)</li>
</ul>

<p>Return the currently open tag of the current XML file (or the empty string if none is open)</p>

<ul>
<li><code>xmlf_GetPretty_print</code> result(<em>logical</em>)</li>
</ul>

<p>Return the current value of pretty_print.</p>

<ul>
<li><code>xmlf_SetPretty_print</code>
<strong>NewValue</strong>: <em>logical</em></li>
</ul>

<p>Set the current value of pretty_print to the NewValue. This may be useful in a mixed namespace
document where pretty printing the output may change the meaning under one of the namespaces.</p>

<h2>Exceptions</h2>

<p><a name="Exceptions"/></p>

<p>Below are explained areas where wxml fails to implement the whole of XML 1.0/1.1. These are divided into two lists; where wxml <strong>does not</strong> permit the generation of a particular well-formed XML document, and where it <strong>does</strong> permit the generation of a particular non-well-formed document.</p>

<p>Ways in which wxml renders it impossible to produce a certain sort of well-formed XML document:</p>

<ol>
<li>Unicode support is limited. Due to the limitations of Fortran, wxml is unable to manipulate characters outwith 7-bit US-ASCII. wxml will ensure that characters corresponding to those in 7-bit ASCII are output correctly within the constraints of the version of XML in use, for a UTF-8 encoding. Attempts to directly output any other characters will have undefined effects.  Output of other unicode characters is possible through the use of character entities.</li>
<li>Due to the constraints of the Fortran IO specification, it is impossible to output arbitrary long strings without carriage returns. The size of the limit varies between processors, but may be as low as 1024 characters. To avoid overrunning this limit, wxml will by default insert carriage returns before every new element, and if an unbroken string of attribute or text data is requested greater than 1024 characters, then carriage returns will be inserted as appropriate; within whitespace if possible; to ensure it is broken up into smaller sections to fit within the limits.</li>
</ol>

<p>wxml will try very hard to ensure that output is well-formed. However, it is possible to fool wxml into producing ill-formed XML documents. Avoid doing so if possible; for completeness these ways are listed here. In all cases where ill-formedness is a possibility, a warning can be issued. These warnings can be verbose, so are off by default, but if they are desired, they can be switched on by manipulating the <code>warning</code> argument to <code>xml_OpenFile</code>.</p>

<ol>
<li>If you specify a non-default text encoding, and then run FoX on a platform which does not use this encoding, then the result will be nonsense, and more than likely ill-formed. FoX will issue a warning in this case.</li>
<li>When adding any text, if any characters are passed in (regardless of character set) which do not have equivalants within 7-bit ASCII, then the results are processor-dependent, and may result in an invalid document on output. A warning will be issued if this occurs. If you need a guarantee that such characters will be passed correctly, use character entities.</li>
<li>If any parameter entities are referenced, no checks are made that the document after parameter-entity-expansion is well-formed. A warning will be issued. </li>
</ol>

<h3>Validity constraints</h3>

<p>Finally, note that constraints on XML documents are divided into two sets - well-formedness constraints (WFC) and validity constraints (VC). The above only applies to WFC checks. wxml can make some minimal checks on VCs, but this is by no means complete, nor is it intended to be. These checks are off by default, but may be switched on by manipulating the <code>validate</code> argument to <code>xml_OpenFile</code>.</p>
</div><hr/><div class="DoX">
<a name="FoX_wcml"/>
<h1>WCML</h1>

<p>WCML is a library for outputting <a href="http://www.xml-cml.org">CML</a> data. It wraps all the necessary XML calls, such that you should never need to touch any <a href="#FoX_wxml">WXML</a> calls when outputting CML.</p>

<p>The CML output is conformant to version 2.4 of the CML schema. The output
can also be made conformant to the CompChem convention.</p>

<p>The available functions and their intended use are listed below. Quite deliberately, no reference is made to the actual CML output by each function. </p>

<p>Wcml is <em>not</em> intended to be a generalized Fortran CML output layer. rather it is intended to be a library which allows the output of a limited set of well-defined syntactical fragments.</p>

<p>Further information on these fragments, and on the style of CML generated here, is available at <a href="http://www.uszla.me.uk/specs/subset.html">http://www.uszla.me.uk/specs/subset.html</a>.</p>

<p>This section of the manual will detail the available CML output subroutines.</p>

<h2>Use of WCML</h2>

<p>wcml subroutines can be accessed from within a module or subroutine by inserting</p>

<pre><code> use FoX_wcml
</code></pre>

<p>at the start. This will import all of the subroutines described below, plus the derived type <code>xmlf_t</code> needed to manipulate a CML file.</p>

<p><em>No</em> other entities will be imported; public/private Fortran namespaces are very carefully  controlled within the library.</p>

<h2>Dictionaries.</h2>

<p>The use of dictionaries with WCML is strongly encouraged. (For those not conversant with dictionaries, a fairly detailed explanation is available at <a href="http://www.xml-cml.org/information/dictionaries">http://www.xml-cml.org/information/dictionaries</a>)</p>

<p>In brief, dictionaries are used in two ways.</p>

<h3>Identification</h3>

<p>Firstly, to identify and disambiguate output data. Every output function below takes an optional argument, <code>dictRef=""</code>. It is intended that every piece of data output is tagged with a dictionary reference, which will look something like <code>nameOfCode:nameOfThing</code>. </p>

<p>So, for example, in SIESTA, all the energies are output with different dictRefs, looking like: <code>siesta:KohnShamEnergy</code>, or <code>siesta:kineticEnergy</code>, etc. By doing this, we can ensure that later on all these numbers can be usefully identified.</p>

<p>We hope that ultimately, dictionaries can be written for codes, which will explain what some of these names might mean. However, it is not in any way necessary that this be done - and using <code>dictRef</code> attributes will help merely by giving the ability to disambiguate otherwise indistinguishable quantities.</p>

<p>We strongly recommend this course of action - if you choose to do follow our recommendation, then you should add a suitable Namespace to your code. That is, immediately <em>after</em> <code>cmlBeginFile</code> and <em>before</em> <code>cmlStartCml</code>, you should add something like:</p>

<pre><code>call cmlAddNamespace(xf=xf, 'nameOfCode', 'WebPageOfCode')
</code></pre>

<p>Again, for SIESTA, we add:</p>

<pre><code>call cmlAddNamespace(xf, 'siesta, 'http://www.uam.es/siesta')
</code></pre>

<p>If you don't have a webpage for your code, don't worry; the address is only used as an identifier, so anything that looks like a URL, and which nobody else is using, will suffice.</p>

<h3>Quantification</h3>

<p>Secondly, we use dictionaries for units. This is compulsory (unlike <code>dictRef</code>s above). Any numerical quantity that is output through cmlAddProperty or cmlAddParameter is <em>required</em> to carry units. These are added with the <code>units=""</code> argument to the function. In addition, every other function below which will take numerical arguments also will take optional units, although default will be used if no units are supplied.</p>

<p>Further details are supplied in section <a href="#Units">Units</a> below.</p>

<h3>General naming conventions for functions.</h3>

<p>Functions are named in the following way:</p>

<ul>
<li><p>All functions begin 
<code>cml</code></p></li>
<li><p>To begin and end a section of the CML file,
a pair of functions will exist:</p>

<ul>
<li><code>cmlStart</code>something</li>
<li><code>cmlEnd</code>something</li>
</ul></li>
<li><p>To output a given quantity/property/concept etc. a function will exist
<code>cmlAdd</code>something</p></li>
</ul>

<h3>Conventions used below.</h3>

<ul>
<li>Function names are in <code>monospace</code></li>
<li>argument names are in <strong>bold</strong></li>
<li>optional argument names are in (<strong>parenthesized bold</strong>)</li>
<li>argument types are in <em>italic</em> and may consist of:</li>
<li><em>string</em>: string of arbitrary (unless otherwise specified) length</li>
<li><em>integer</em>: default integer</li>
<li><em>real(sp)</em>: single precision real number</li>
<li><em>real(dp)</em>: double precision real number</li>
<li><em>logical</em>: default logical </li>
<li><em>real</em>: either of <em>real(sp)</em> or <em>real(dp)</em></li>
<li><em>anytype</em>: any of <em>logical</em>, <em>integer</em>, <em>real(sp)</em>, <em>real(dp)</em>, <em>string</em></li>
</ul>

<p>Note that where <em>strings</em> are passed in, they will be passed through entirely unchanged to the output file - no truncation of whitespace will occur.</p>

<p>Also note that wherever a <em>real</em> number can be passed in (including through <em>anytype</em>) then the formatting can be specified using the conventions described in <a href="#StringFormatting">StringFormatting</a></p>

<ul>
<li><em>scalar</em>: single item</li>
<li><em>array</em>: one-dimensional array of items</li>
<li><em>matrix</em>: two-dimensional array of items</li>
<li><em>anydim</em>: any of <em>scalar</em>, <em>array</em>, <em>matrix</em></li>
</ul>

<p>Where an <em>array</em> is passed in, it may be passed either as an assumed-shape array; that is, as an F90-style array with no necessity for specifying bounds; thusly:</p>

<pre><code>integer :: array(50)
call cmlAddProperty(xf, 'coords', array)
</code></pre>

<p>or as an assumed-size array; that is, an F77-style array, in which case the length must be passed as an additional parameter:</p>

<pre><code>integer :: array(*)
call cmlAddProperty(xf, 'coords', array, nitems=50)
</code></pre>

<p>Similarly, when a <em>matrix</em> is passed in, it may be passed in both fashions:</p>

<pre><code>integer :: matrix(50, 50)
call cmlAddProperty(xf, 'coords', matrix)
</code></pre>

<p>or </p>

<pre><code>integer :: array(3, *)
call cmlAddProperty(xf, 'coords', matrix, nrows=3, ncols=50)
</code></pre>

<p>All functions take as their first argument an XML file object, whose keyword is always <code>xf</code>. This file object is initialized by a <code>cmlBeginFile</code> function.</p>

<p>It is <em>highly</em> recommended that subroutines be called with keywords specified rather than relying on the implicit ordering of arguments. This is robust against changes in the library calling convention; and also stepsides a significant cause of errors when using subroutines with large numbers of arguments.</p>

<p><a name="Units"/></p>

<h3>Units</h3>

<p>Note below that the functions <code>cmlAddParameter</code> and <code>cmlAddProperty</code> both <em>require</em> that units be specified for any numerical quantities output.</p>

<p>If you are trying to output a quantity that is genuinely dimensionless, then you should specify <code>units="units:dimensionless"</code>; or if you are trying to output a countable quantity (eg number of CPUs) then you may specify <code>units="units:countable"</code>.</p>

<p>For other properties, all units should be specified as namespaced quantities. If you are using
a very few common units, it may be easiest to borrow definitions from the provided dictionaries;</p>

<p>(These links do not resolve yet.)</p>

<p><code>cmlUnits: http://www.xml-cml.org/units/units</code> <br />
<code>siUnits: http://www.xml-cml.org/units/siUnits</code> <br />
<code>atomicUnits: http://www.xml-cml.org/units/atomic</code>  </p>

<p>A default units dictionary, containing only the very basic units that wcml needs to know about, which has a namespace of: <code>http://www.uszla.me.uk/FoX/units</code>, and wcml assigns it automatically to the prefix <code>units</code>.</p>

<p>This is added <em>automatically</em>, so attempts to add it manually will fail.</p>

<p>The contents of all of these dictionaries, plus the wcml dictionary, may be viewed at:
<a href="http://www.uszla.me.uk/unitsviz/units.cgi">http://www.uszla.me.uk/unitsviz/units.cgi</a>.</p>

<p>Otherwise, you should feel at liberty to construct your own namespace;
declare it using <code>cmlAddNamespace</code>, and markup all your units as:</p>

<pre><code> units="myNamespace:myunit"
</code></pre>

<h2>Functions for manipulating the CML file:</h2>

<ul>
<li><code>cmlBeginFile</code> <br />
<strong>filename</strong>: <em>string</em> <em>scalar</em>: Filename to be opened. <br />
<strong>unit</strong>: <em>integer</em> <em>scalar</em>: what unit number should the file be opened on? If you don't
care, you may specify <code>-1</code> as the unit number, in which case wcml will make a guess <br />
(<strong>replace</strong>): <em>logical</em> <em>scalar</em>: should the file be replaced if it already exists? <em>default: yes</em></li>
</ul>

<p>This takes care of all calls to open a CML output file.</p>

<ul>
<li><code>cmlFinishFile</code></li>
</ul>

<p>This takes care of all calls to close an open CML output file, once you have finished with it. It is compulsory to call this - if your program finished without calling this, then your CML file will be invalid.</p>

<ul>
<li><code>cmlAddNamespace</code> <br />
<strong>prefix</strong> <em>string</em> <em>scalar</em>: prefix to be used <br />
<strong>URI</strong> <em>string</em> <em>scalar</em>: namespace URI to be used  </li>
</ul>

<p>This adds a namespace to a CML file. <br />
NB This may only ever be called immediately after a <code>cmlBeginFile</code> call, before any
output has been performed.
Attempts to do otherwise will result in a runtime error.</p>

<p>This will be needed if you are adding dictionary references to your output. Thus for siesta, we do:</p>

<pre><code>call cmlAddNamespace(xf, 'siesta', 'http://www.uam.es/siesta')
</code></pre>

<p>and then output all our properties and parameters with <code>dictRef="siesta:something"</code>.</p>

<ul>
<li><p><code>cmlStartCml</code> <br />
(<strong>fileId</strong>) <em>string</em> <em>scalar</em>: name of originating file.  (default: current filename) <br />
(<strong>version</strong>) <em>string</em> <em>scalar</em>: version of CML in use.  (default: 2.4) <br />
(<strong>compchem</strong>) <em>logical</em> <em>scalar</em>: add extra namespace declarations needed by the recent compchem CML convention. This provides a minimum level of infrastructure needed to create valid compchem documents. (default: false)</p></li>
<li><p><code>cmlEndCml</code></p></li>
</ul>

<p>This pair of functions begin and end the CML output to an existing CML file. It takes care of namespaces.</p>

<p>Note that unless specified otherwise, there will be a <code>convention</code> attribute added to the <code>cml</code> tag specifying <code>FoX_wcml-2.0</code> as the convention. (see <a href="http://www.uszla.me.uk/FoX">http://www.uszla.me.uk/FoX</a> for details)</p>

<h2>Start/End sections</h2>

<ul>
<li><p><code>cmlStartMetadataList</code> <br />
(<strong>name</strong>) <em>string</em> <em>scalar</em>: name for the metadata list <br />
(<strong>role</strong>) <em>string</em> <em>scalar</em> role which the element plays </p></li>
<li><p><code>cmlEndMetadataList</code></p></li>
</ul>

<p>This pair of functions open &amp; close a metadataList, which is a wrapper for metadata items.</p>

<ul>
<li><p><code>cmlStartParameterList</code> <br />
(<strong>ref</strong>) <em>string</em> <em>scalar</em>: Reference an <code>id</code> attribute of another element (generally deprecated) <br />
(<strong>role</strong>) <em>string</em> <em>scalar</em> role which the element plays </p></li>
<li><p><code>cmlEndParameterList</code></p></li>
</ul>

<p>This pair of functions open &amp; close a parameterList, which is a wrapper for input parameters.</p>

<ul>
<li><p><code>cmlStartPropertyList</code> <br />
(<strong>ref</strong>) <em>string</em> <em>scalar</em>: Reference an <code>id</code> attribute of another element (generally deprecated) <br />
(<strong>role</strong>) <em>string</em> <em>scalar</em> role which the element plays </p></li>
<li><p><code>cmlEndPropertyList</code></p></li>
</ul>

<p>This pair of functions open &amp; close a propertyList, which is a wrapper for output properties.</p>

<ul>
<li><code>cmlStartKpointList</code></li>
<li><code>cmlEndKpointList</code></li>
</ul>

<p>Start/end a list of k-points (added using <code>cmlAddKpoint</code> below)</p>

<ul>
<li><code>cmlStartModule</code> <br />
(<strong>serial</strong>) <em>string</em> <em>scalar</em>: serial id for the module 
(<strong>title</strong>) <em>string</em> <em>scalar</em>: title for module element
(<strong>role</strong>) <em>string</em> <em>scalar</em>: role which the element plays </li>
</ul>

<p>Note that in most cases where you might want to use a serial number, you should probably be using the <code>cmlStartStep</code> subroutine below.</p>

<ul>
<li><code>cmlEndModule</code></li>
</ul>

<p>This pair of functions open &amp; close a module of a computation which is unordered, or loosely-ordered. For example, METADISE uses one module for each surface examined.</p>

<ul>
<li><p><code>cmlStartStep</code> <br />
(<strong>index</strong>) <em>integer</em> <em>scalar</em>: index number for the step. In the absence of an index, steps will be assumed to be consecutively numbered. Specifying this is useful if you wish to output <em>eg</em> every hundredth step. <br />
(<strong>type</strong>) <em>string</em> <em>scalar</em>: what sort of step is this? This should be a namespaced string, for example: <code>siesta:CG</code> is a Conjugate Gradient step in siesta.</p></li>
<li><p><code>cmlEndStep</code></p></li>
</ul>

<p>This pair of functions open and close a module of a computation which is strongly ordered. For example, DLPOLY uses steps for each step of the simulation.</p>

<h2>Adding items.</h2>

<ul>
<li><code>cmlAddMetadata</code> <br />
<strong>name</strong>: <em>string</em> <em>scalar</em>: Identifying string for metadata <br />
<strong>content</strong>: <em>character</em> <em>scalar</em>: Content of metadata  </li>
</ul>

<p>This adds a single item of metadata. Metadata vocabulary is completely uncontrolled within WCML. This means that metadata values may <em>only</em> be strings of characters. If you need your values to contain numbers, then you need to define the representation yourself, and construct your own strings.</p>

<ul>
<li><code>cmlAddParameter</code> <br />
<strong>name</strong>: <em>string</em> <em>scalar</em>: Identifying title for parameter <br />
<strong>value</strong>:<em>anytype</em> <em>anydim</em>: value of parameter <br />
<strong>units</strong>: <em>string</em> <em>scalar</em>: units of parameter value  (optional for logical/character <strong>value</strong>s, compulsory otherwise; see note above) <br />
(<strong>constraint</strong>) <em>string</em> <em>scalar</em>: Constraint under which the parameter is set (this can be an arbitrary string) <br />
(<strong>ref</strong>) <em>string</em> <em>scalar</em>: Reference an <code>id</code> attribute of another element (generally deprecated) <br />
(<strong>role</strong>) <em>string</em> <em>scalar</em> role which the element plays </li>
</ul>

<p>This function adds a tag representing an input parameter</p>

<ul>
<li><code>cmlAddProperty</code> <br />
<strong>title</strong>: <em>string</em> <em>scalar</em> <br />
<strong>value</strong>: <em>any</em> <em>anydim</em> <br />
<strong>units</strong>: <em>string</em> <em>scalar</em> units of property value  (optional for logical/character <strong>value</strong>s, compulsory otherwise; see note above) <br />
(<strong>ref</strong>) <em>string</em> <em>scalar</em>: Reference an <code>id</code> attribute of another element (generally deprecated) <br />
(<strong>role</strong>) <em>string</em> <em>scalar</em> role which the element plays </li>
</ul>

<p>This function adds a tag representing an output property</p>

<h2>Adding geometry information</h2>

<ul>
<li><code>cmlAddMolecule</code> <br />
<strong>coords</strong>: <em>real</em>: a 3xn matrix of real numbers representing atomic coordinates (either fractional or Cartesian) . These <em>must</em> be specified in Angstrom or fractional units (see <strong>style</strong> below.) <br />
<strong>OR</strong> <br />
<strong>x</strong>, <strong>y</strong>, <strong>z</strong>: <em>real</em>: 3 one-dimensional arrays containing the <em>x</em>, <em>y</em>, and <em>z</em> coordinates of the atoms in the molecule.  These <em>must</em> be specified in Angstrom or fractional units (see <strong>style</strong> below.) <br />
<strong>elements</strong>: <em>string</em> <em>array</em>: a length-n array of length-2 strings containing IUPAC chemical symbols for the atoms <br />
(<strong>natoms</strong>) <em>integer</em> <em>scalar</em>: number of atoms in molecule (default: picked up from length of <strong>coords</strong> array) <br />
(<strong>occupancies</strong>): <em>real</em> <em>array</em> : a length-n array of the occupancies of each atom. <br />
(<strong>atomRefs</strong>): <em>string</em> <em>array</em>: a length-n array of strings containing references which may point to IDs elsewhere of, for example, pseudopotentials or basis sets defining the element's behaviour. <br />
(<strong>atomIds</strong>): <em>string</em> <em>array</em>: a length-n array of strings containing IDs for the atoms. <br />
(<strong>style</strong>): <em>string</em> <em>scalar</em>: <code>cartesian</code> - the coordinates are Cartesian, or <code>fractional</code> - the coordinates are fractional. The default is Cartesian. <br />
(<strong>ref</strong>) <em>string</em> <em>scalar</em>: Reference an <code>id</code> attribute of another element (generally deprecated) <br />
(<strong>formula</strong>) <em>string</em> <em>scalar</em>: An IUPAC chemical formula <br />
(<strong>chirality</strong>) <em>string</em> <em>scalar</em>: The chirality of the molecule. No defined vocabulary. <br />
(<strong>role</strong>) <em>string</em> <em>scalar</em>: Role of molecule. No defined vocabulary. <br />
(<strong>bondAtom1Refs</strong>) <em>string</em> <em>array</em>: Length-m array of references to atomIds at one "end" of a list of bonds. <br />
(<strong>bondAtom2Refs</strong>) <em>string</em> <em>array</em>: Length-m array of references to atomIds at another "end" of a list of bonds. <br />
(<strong>bondOrders</strong>) <em>string</em> <em>array</em>: Length-m array of bond orders. See below. <br />
(<strong>bondIds</strong>) <em>string</em> <em>array</em>: Length-m array of strings containing IDs for bonds. <br />
(<strong>nobondcheck</strong>) <em>logical</em> <em>scalar</em>: Enable (.true., the default) of dissable (.false.) bond validition.   </li>
</ul>

<p>Outputs an atomic configuration. Bonds may be added using the optional arguments <strong>bondAtom1Refs</strong>, <strong>bondAtom2Refs</strong> and <strong>bondOrders</strong>. All these arrays must be the same lenght and all must be present if bonds are to be added. Optionally, <strong>bondIds</strong> can be used to add Ids to the bond elements. Some valididity constraints are imposed (atomsRefs in the bonds must be defined, bonds cannot be added twice). The meaning of the terms "molecule", "bond" and "bond order" is left loosly defined.</p>

<ul>
<li><code>cmlAddLattice</code> <br />
<strong>cell</strong>: <em>real</em> <em>matrix</em> a 3x3 matrix of the unit cell <br />
(<strong>spaceType</strong>): <em>string</em> <em>scalar</em>: <code>real</code> or <code>reciprocal</code> space. <br />
(<strong>latticeType</strong>): <em>string</em> <em>scalar</em> Space group of the lattice. No defined vocabulary <br />
(<strong>units</strong>): <em>string</em> <em>scalar</em> units of (reciprocal) distance that cell vectors is given in;
<em>default: Angstrom</em></li>
</ul>

<p>Outputs information about a unit cell, in lattice-vector form</p>

<ul>
<li><code>cmlAddCrystal</code> <br />
<strong>a</strong>: <em>real</em> <em>scalar</em> the 'a' parameter (must be in Angstrom) <br />
<strong>b</strong>: <em>real</em> <em>scalar</em> the 'b' parameter <br />
<strong>c</strong>: <em>real</em> <em>scalar</em> the 'c' parameter <br />
<strong>alpha</strong>: <em>real</em> <em>scalar</em> the 'alpha' parameter <br />
<strong>beta</strong>: <em>real</em> <em>scalar</em> the 'beta' parameter <br />
<strong>gamma</strong>: <em>real</em> <em>scalar</em> the 'gamma' parameter <br />
(<strong>z</strong>): <em>integer</em> <em>scalar</em> the 'z' parameter: number of molecules per unit cell. <br />
(<strong>lenunits</strong>): <em>string</em> <em>scalar</em>: Units of length: default is <code>units:angstrom</code> <br />
(<strong>angunits</strong>): <em>string</em> <em>scalar</em>: Units of angle: default is <code>units:degrees</code> <br />
(<strong>lenfmt</strong>): <em>string</em> <em>scalar</em>: format for crystal lengths <br />
(<strong>angfmt</strong>): <em>string</em> <em>scalar</em>: format for crystal angles <br />
(<strong>spaceGroup</strong>): <em>string</em> <em>scalar</em> Space group of the crystal. No defined vocabulary.</li>
</ul>

<p>Outputs information about a unit cell, in crystallographic form</p>

<h2>Adding eigen-information</h2>

<ul>
<li><code>cmlStartKPoint</code> <br />
<strong>kpoint</strong>: <em>real</em> <em>array-3</em> the reciprocal-space coordinates of the k-point <br />
(<strong>weight</strong>): <em>real</em> <em>scalar</em> the weight of the kpoint <br />
(<strong>kptfmt</strong>): <em>string</em> <em>scalar</em> numerical formatting for the k-point <br />
(<strong>wtfmt</strong>): <em>string</em> <em>scalar</em> numerical formatting for the weight</li>
</ul>

<p>Start a kpoint section.</p>

<ul>
<li><code>cmlEndKPoint</code>  </li>
</ul>

<p>End a kpoint section.</p>

<ul>
<li><code>cmlAddKPoint</code> <br />
<strong>kpoint</strong>: <em>real</em> <em>array-3</em> the reciprocal-space coordinates of the k-point <br />
(<strong>weight</strong>): <em>real</em> <em>scalar</em> the weight of the kpoint <br />
(<strong>kptfmt</strong>): <em>string</em> <em>scalar</em> numerical formatting for the k-point <br />
(<strong>wtfmt</strong>): <em>string</em> <em>scalar</em> numerical formatting for the weight</li>
</ul>

<p>Add an empty kpoint section.</p>

<ul>
<li><code>cmlStartBand</code> <br />
(<strong>spin</strong>): <em>string</em> <em>scalar</em> the spin of this band. Must be either "up" or "down" <br />
(<strong>label</strong>): the label of this band.</li>
</ul>

<p>Start a section describing one band.</p>

<ul>
<li><code>cmlEndBand</code></li>
</ul>

<p>End a section describing one band.</p>

<ul>
<li><code>cmlAddEigenValue</code> <br />
<strong>value</strong>: <em>real</em> <em>scalar</em> the eigenvalue <br />
<strong>units</strong>: <em>QName</em> <em>scalar</em> the units of the eigenvalue</li>
</ul>

<p>Add a single eigenvalue to a band.</p>

<ul>
<li><code>cmlAddBandList</code> <br />
<strong>values</strong>: <em>real</em> <em>array</em> the eigenvalues <br />
<strong>spin</strong>: <em>string</em> <em>scalar</em> the spin orientation ("up" or "down") <br />
<strong>units</strong>: <em>QName</em> <em>scalar</em> the units of the eigenvalue</li>
</ul>

<p>Add a list of eigenvalues for a kpoint</p>

<ul>
<li><code>cmlAddEigenValueVector</code>
<strong>value</strong>: <em>real</em> <em>scalar</em> the eigenvalue for this band <br />
<strong>units</strong>: <em>QName</em> <em>scalar</em> the units of the eigenvalue <br />
<strong>vector</strong>: <em>real/complex</em> <em>3xN matrix</em> the eigenvectors for this band <br />
(<strong>valfmt</strong>): <em>string</em> <em>scalar</em> numerical formatting for the eigenvalue <br />
(<strong>vecfmt</strong>): <em>string</em> <em>scalar</em> numerical formatting for the eigenvector</li>
</ul>

<p>Add a phononic eigenpoint to the band - which has a single energy, and a 3xN matrix representing the eigenvector.</p>

<h2>Echoing input files</h2>

<p>It is often considered useful to include a direct representation of
input data within an applications output files. FoX_wcml contains a
number of procedures to allow this in a CML document based on a specification
described in a manuscript currently in review (de Jong, Walker and Hanwell 
"From Data to Analysis: Linking NWChem and Avogadro with the Syntax and 
Semantics of Chemical Markup Language". 
The approach is also designed to make data recovery using an 
XSL transform straightforward. File metadata such as the 
original filename is also accessible. We assume that only ASCII 
data must be stored, arbitrary binary files are 
out of scope as are XML documents and non-ASCII textural data.
Two methods are provided with the 
most appropriate being dependent on the design of the application.</p>

<h3>Using file names</h3>

<ul>
<li><code>cmlDumpDec</code>
<strong>inputDec</strong>: <em>string</em> <em>scalar</em> or <em>array</em> file name(s) to be used
<strong>line<em>lengths</strong>: *integer* *scalar* or *array* miximum number of characters per line
<strong>trim</em>lines</strong>: <em>logical</em> <em>scalar</em> or <em>array</em> should tralining whitespace be removed?
(<strong>iostat</strong>): <em>nteger</em> <em>scalar</em> output argument indicating errors.</li>
</ul>

<p>In the this approach the single subroutine, <code>cmlDumpInputDec</code>, is called 
with an array of file names as input arguments. In turn each file is 
opened, its contents are written to the CML document in the appropriate 
form, before the file is closed. </p>

<h3>Line by line</h3>

<ul>
<li><code>cmlStartDecList</code></li>
</ul>

<p>Start an outer wrapper for input data.</p>

<ul>
<li><code>cmlEndDecList</code></li>
</ul>

<p>End the outer wrapper.</p>

<ul>
<li><code>cmlStartDec</code>
<strong>filename</strong>: <em>string</em> <em>scalar</em> file name to be used</li>
</ul>

<p>Start a wrapper for a single "file" or similar concept.</p>

<ul>
<li><code>cmlEndDec</code></li>
</ul>

<p>End the file wrapper.</p>

<ul>
<li><code>cmlAddDecLine</code>
<strong>text</strong>: <em>string</em> <em>scalar</em> A line of text from an input file to add</li>
</ul>

<p>Put a line of text into the file wrapper.</p>

<p>The convoluted nature of file handling 
in Fortran combined with the way that some applications read their input 
data means that this approach is not always available (for example, if 
the input file is held open for the duration of the calculation, or if 
data is read from standard input) so an alternative interface with five 
subroutines (<code>cmlStartDecList</code>, <code>cmlStartDec</code>, 
<code>cmlAddDecLine</code>, <code>cmlEndDec</code> and <code>cmlEndDecList</code>) 
is provided. These must be called in order (and usually in two loops, 
one over files, and an inner loop over lines in each file).</p>

<h2>Common arguments</h2>

<p>All <code>cmlAdd</code> and <code>cmlStart</code> routines take the following set of optional arguments:</p>

<ul>
<li><code>id</code>: Unique identifying string for element. (Uniqueness is not enforced, though duplicated ids on output are usually an error and may cause later problems)  </li>
<li><code>title</code>: Human-readable title of element for display purposes  </li>
<li><code>dictRef</code>: reference to disambiguate element. Should be a QName; a namespaced string. An actual dictionary entry may or may not exist. It is not an error for it not to.  </li>
<li><code>convention</code>: convention by which the element is to be read. <br />
(The wording of the definitions for <code>convention</code> is deliberately loose.)</li>
</ul>
</div><hr/><div class="DoX">
<a name="FoX_wkml"/>
<h1>WKML</h1>

<p>WKML is a library for creating <a href="http://www.opengeospatial.org/standards/kml/">KML</a> 
documents. These documents are intended to be used for "expressing geographic 
annotation and visualization" for maps and Earth browsers such as 
<a href="http://earth.google.co.uk/">Google Earth</a> or <a href="http://edu.kde.org/marble/">Marble</a>.
WKML wraps all the necessary XML calls, such that you should never need to touch any
<a href="#FoX_wxml">WXML</a> calls when outputting KML from a Fortran application.</p>

<p>WKML is intended to produce XML documents that conform to version 2.2 of the Open
Geospatial Consortium's <a href="http://schemas.opengis.net/kml/2.2.0/ogckml22.xsd">schema</a>.
However, the library offers no guarantee that documents produced will be valid as 
only a small subset of the constraints are enforced. The API is designed to minimize 
the possibilty of producing invalid KML in common use cases, and well-formdness is
maintained by the underlying WXML library.</p>

<p>The available functions and their intended use are listed below. One useful reference to
the use of KML is Google's <a href="http://code.google.com/apis/kml/documentation/">KML documentation</a>.</p>

<h2>Use of WKML</h2>

<p>wkml subroutines can be accessed from within a module or subroutine by inserting</p>

<pre><code> use FoX_wkml
</code></pre>

<p>at the start. This will import all of the subroutines described below, plus the derived type <code>xmlf_t</code> needed to manipulate a KML file.</p>

<p><em>No</em> other entities will be imported; public/private Fortran namespaces are very carefully controlled within the library.</p>

<h3>Conventions used below.</h3>

<ul>
<li>Function names are in <code>monospace</code></li>
<li>argument names are in <strong>bold</strong></li>
<li>optional argument names are in (<strong>parenthesized bold</strong>)  </li>
<li>argument types are in <em>italic</em> and may consist of:  </li>
<li><em>string</em>: string of arbitrary (unless otherwise specified) length</li>
<li><em>integer</em>: default integer</li>
<li><em>real(sp)</em>: single precision real number</li>
<li><em>real(dp)</em>: double precision real number</li>
<li><em>logical</em>: default logical</li>
<li><em>real</em>: either of <em>real(sp)</em> or <em>real(dp)</em></li>
<li>arguments may be:</li>
<li><em>scalar</em>: single item</li>
<li><em>array</em>: one-dimensional array of items</li>
<li><em>matrix</em>: two-dimensional array of items</li>
<li><em>anydim</em>: any of <em>scalar</em>, <em>array</em>, <em>matrix</em></li>
</ul>

<p>All functions take as their first argument an XML file object, whose
keyword is always <code>xf</code>. This file object is initialized by a <code>kmlBeginFile</code> function.</p>

<p>It is <em>highly</em> recommended that subroutines be called with keywords
specified rather than relying on the implicit ordering of arguments.
This is robust against changes in the library calling convention; and 
also stepsides a significant cause of errors when using subroutines
with large numbers of arguments.</p>

<h2>Functions for manipulating the KML file:</h2>

<ul>
<li><code>kmlBeginFile</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object <br />
<strong>filename</strong>: <em>string</em> <em>scalar</em>: Filename to be opened. <br />
<strong>unit</strong>: <em>integer</em> <em>scalar</em>: what unit number should the file be opened on? If you don't
care, you may specify <code>-1</code> as the unit number, in which case wkml will make a guess <br />
(<strong>replace</strong>): <em>logical</em> <em>scalar</em>: should the file be replaced if it already exists? <em>default: yes</em> <br />
(<strong>docName</strong>): <em>string</em> <em>scalar</em>: an optional name for the outermost document element. If absent, "WKML output" will be used</li>
</ul>

<p>This takes care of all calls to open a KML output file.</p>

<ul>
<li><code>kmlFinishFile</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object </li>
</ul>

<p>This takes care of all calls to close an open KML output file, once
you have finished with it. It is compulsory to call this - if your
program finished without calling this, then your KML file will be
invalid.</p>

<ul>
<li><code>kmlOpenFolder</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object <br />
(<strong>name</strong>): <em>string</em> <em>scalar</em>: an optional name for the new folder. <br />
(<strong>id</strong>): <em>string</em> <em>scalar</em>: an optional xml id for the new folder. </li>
</ul>

<p>This starts a new folder. Folders are used in KML to organize other
objects into groups, the visability of these groups can be changed 
in one operation within Google Earth. Folders can be nested.</p>

<ul>
<li><code>kmlCloseFolder</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object </li>
</ul>

<p>This closes the current folder. </p>

<ul>
<li><code>kmlOpenDocument</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object <br />
<strong>name</strong>: <em>string</em> <em>scalar</em>: a name for the new document element. <br />
(<strong>id</strong>): <em>string</em> <em>scalar</em>: an optional xml id for the new document element. </li>
</ul>

<p>This starts a new document element at this point in the output. Note that no
checks are currently performed to ensure that this is permitted, for example
only one document is permitted to be a child of the kml root element. Most
users should not need to use this subroutine.</p>

<ul>
<li><code>kmlCloseDocument</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object </li>
</ul>

<p>This closes the current document element. Do not close the outermose document 
element created with <code>kmlBeginFile</code>, this must be closed with <code>kmlFinishFile</code>.
Most users should not need to use this subroutine.</p>

<h2>Functions for producing geometrical objects:</h2>

<ul>
<li><code>kmlCreatePoints</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object <br />
(<strong>extrude</strong>): <em>logical</em> <em>scalar</em>: If altitude is non-zero, should the point be connected to the ground? <br />
(<strong>altitudeMode</strong>): <em>logical</em> <em>scalar</em>: If altitude is specified, is it relativeToGround or absolute? <br />
(<strong>name</strong>): <em>string</em> <em>scalar</em>: A name for the collection of points <br />
(<strong>color</strong>): <em>color_t</em>: Line colour as a kml color type (See Colours) <br />
(<strong>colorname</strong>): <em>string</em> <em>scalar</em>: Line colour as a name (See Colours) <br />
(<strong>colorhex</strong>): <em>string(len=8)</em> <em>scalar</em>: Line colour in hex (See Colours) <br />
(<strong>scale</strong>): <em>real</em> <em>scalar</em>: Scaling size for the point icon. <br />
(<strong>description</strong>): <em>string</em> <em>array</em>: A description for each point. <br />
(<strong>description_numbers</strong>): <em>real</em> <em>array</em>: Numeric description for each point. <br />
(<strong>styleURL</strong>): <em>string</em> <em>scalar</em>: Location of style specification (see Style Handling) <br />
<em>and:</em> <br />
<strong>longitude</strong>: <em>real</em> <em>array</em>: longitude of each point in degrees <br />
<strong>latitude</strong>: <em>real</em> <em>array</em>: latitude of each point in degrees <br />
(<strong>altitude</strong>): <em>real</em> <em>array</em>: altitude of each point in metres <br />
<em>or:</em> <br />
<strong>location</strong>: <em>real</em> <em>matrix</em>: rank-two 2xN array with the longitude of each point in the first row, and the latitude in the second row. In degrees. <br />
(<strong>altitude</strong>): <em>real</em> <em>array</em>: altitude of each point in metres <br />
<em>or:</em> <br />
<strong>location</strong>: <em>real</em> <em>matrix</em>: rank-two 3xN array with the longitude of each point in the first row, the latitude in the second row, and the altitude in the third row. Longitude and latitude in degrees and altitude in metres.  </li>
</ul>

<p>A single function, kmlCreatePoints accepts various combinations of arguments, and will generate a series of individual points to be visualized in Google Earth. In fact, the KML produced will consist of a Folder, containing Placemarks, one for each point. The list of points may be provided in any of the three ways specified above.</p>

<ul>
<li><code>kmlCreateLine</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object <br />
(<strong>closed</strong>): <em>logicl</em> <em>scalar</em>: Should the last point be joined to the first point? <br />
(<strong>extrude</strong>): <em>logical</em> <em>scalar</em>: If altitude is non-zero, should the point be connected to the ground? <br />
(<strong>tessellate</strong>): <em>logical</em> <em>scalar</em>: If altitude is not specified, should the line produced follow the altitude of the ground below it? <br />
(<strong>altitudeMode</strong>): <em>logical</em> <em>scalar</em>: If altitude is specified, is it relativeToGround or absolute? <br />
(<strong>name</strong>): <em>string</em> <em>scalar</em>: A name for the collection of points <br />
(<strong>color</strong>): <em>color_t</em>: Line colour as a kml color type (See Colours) <br />
(<strong>colorname</strong>): <em>string</em> <em>scalar</em>: Line colour as a name (See Colours) <br />
(<strong>colorhex</strong>): <em>string(len=8)</em> <em>scalar</em>: Line colour in hex (See Colours) <br />
(<strong>width</strong>): <em>integer</em> <em>scalar</em>: Width of the lines. <br />
(<strong>scale</strong>): <em>real</em> <em>scalar</em>: Scaling size for the point icon. <br />
(<strong>description</strong>): <em>string</em> <em>array</em>: A description for each point. <br />
(<strong>styleURL</strong>): <em>string</em> <em>scalar</em>: Location of style specification (see Style Handling) <br />
<em>and:</em> <br />
<strong>longitude</strong>: <em>real</em> <em>array</em>: longitude of each point in degrees <br />
<strong>latitude</strong>: <em>real</em> <em>array</em>: latitude of each point in degrees <br />
(<strong>altitude</strong>): <em>real</em> <em>array</em>: altitude of each point in metres <br />
<em>or:</em> <br />
<strong>location</strong>: <em>real</em> <em>matrix</em>: rank-two 2xN array with the longitude of each point in the first row, and the latitude in the second row. In degrees. <br />
(<strong>altitude</strong>): <em>real</em> <em>array</em>: altitude of each point in metres <br />
<em>or:</em> <br />
<strong>location</strong>: <em>real</em> <em>matrix</em>: rank-two 3xN array with the longitude of each point in the first row, the latitude in the second row, and the altitude in the third row. Longitude and latitude in degrees and altitude in metres.  </li>
</ul>

<p>A single function, kmlCreateLine accepts various combinations of arguments, and will generate a series of individual points to be visualized as a (closed or open) path in Google Earth. In fact, the KML produced will consist of a LineString, or LinearRing, containing a list of coordinates. The list of points may be provided in any of the three ways specified above.</p>

<ul>
<li><code>kmlStartRegion</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object <br />
(<strong>extrude</strong>): <em>logical</em> <em>scalar</em>: If altitude is non-zero, should the point be connected to the ground? <br />
(<strong>tessellate</strong>): <em>logical</em> <em>scalar</em>: If altitude is not specified, should the line produced follow the altitude of the ground below it? <br />
(<strong>altitudeMode</strong>): <em>logical</em> <em>scalar</em>: If altitude is specified, is it relativeToGround or absolute? <br />
(<strong>name</strong>): <em>string</em> <em>scalar</em>: A name for the region <br />
(<strong>fillcolor</strong>): <em>color_t</em>: Region colour as a kml color type (See Colours) <br />
(<strong>fillcolorname</strong>): <em>string</em> <em>scalar</em>: Region  colour as a name (See Colours) <br />
(<strong>fillcolorhex</strong>): <em>string(len=8)</em> <em>scalar</em>: Region colour in hex (See Colours) <br />
(<strong>linecolor</strong>): <em>color_t</em>: Line colour as a kml color type (See Colours) <br />
(<strong>linecolorname</strong>): <em>string</em> <em>scalar</em>: Line colour as a name (See Colours) <br />
(<strong>linecolorhex</strong>): <em>string(len=8)</em> <em>scalar</em>: Line colour in hex (See Colours) <br />
(<strong>linewidth</strong>): <em>integer</em> <em>scalar</em>: Width of the line. <br />
(<strong>description</strong>): <em>string</em> <em>scalar</em>: A description for the region. <br />
(<strong>styleURL</strong>): <em>string</em> <em>scalar</em>: Location of style specification (see Style Handling) <br />
<em>and:</em> <br />
<strong>longitude</strong>: <em>real</em> <em>array</em>: longitude of each point in degrees <br />
<strong>latitude</strong>: <em>real</em> <em>array</em>: latitude of each point in degrees <br />
(<strong>altitude</strong>): <em>real</em> <em>array</em>: altitude of each point in metres <br />
<em>or:</em> <br />
<strong>location</strong>: <em>real</em> <em>matrix</em>: rank-two 2xN array with the longitude of each point in the first row, and the latitude in the second row. In degrees. <br />
(<strong>altitude</strong>): <em>real</em> <em>array</em>: altitude of each point in metres <br />
<em>or:</em> <br />
<strong>location</strong>: <em>real</em> <em>matrix</em>: rank-two 3xN array with the longitude of each point in the first row, the latitude in the second row, and the altitude in the third row. Longitude and latitude in degrees and altitude in metres.  </li>
</ul>

<p>Creates a filled region with the outer boundary described by the list of points. May be followed by one or more calls to <code>kmlAddInnerBoundary</code> and these must be followed by a call to <code>kmlAddInnerBoundary</code>.</p>

<ul>
<li><code>kmlEndRegion</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object  </li>
</ul>

<p>Ends the specification of a region with or without inner boundaries.</p>

<ul>
<li><code>kmlAddInnerBoundary</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object <br />
<em>and:</em> <br />
<strong>longitude</strong>: <em>real</em> <em>array</em>: longitude of each point in degrees <br />
<strong>latitude</strong>: <em>real</em> <em>array</em>: latitude of each point in degrees <br />
(<strong>altitude</strong>): <em>real</em> <em>array</em>: altitude of each point in metres <br />
<em>or:</em> <br />
<strong>location</strong>: <em>real</em> <em>matrix</em>: rank-two 2xN array with the longitude of each point in the first row, and the latitude in the second row. In degrees. <br />
(<strong>altitude</strong>): <em>real</em> <em>array</em>: altitude of each point in metres <br />
<em>or:</em> <br />
<strong>location</strong>: <em>real</em> <em>matrix</em>: rank-two 3xN array with the longitude of each point in the first row, the latitude in the second row, and the altitude in the third row. Longitude and latitude in degrees and altitude in metres.  </li>
</ul>

<p>Introduces an internal area that is to be excluded from the enclosing region.</p>

<h2>2D fields</h2>

<p>WKML also contains two subroutines to allow scalar fields to be plotted over a geographical 
region. Data is presented to WKML as a collection of values and coordinates and this data 
can be displayed as a set of coloured cells, or as isocontours.</p>

<h3>Data input</h3>

<p>For all 2-D field subroutines both position and value of the data must be specified. The data values
must always be specified as a rank-2 array, <em>values(:,:)</em>. The grid can be specified in three ways 
depending on grid type.</p>

<ul>
<li>Regular rectangular grid: Specify north, south, east, west. These specify the four corners of the grid (which must be aligned with lines of longitude and latitude).  </li>
<li>Irregularly spaced rectangular grid. Specify two rank-one arrays, longitude(:) and latitude(:). The grid must be aligned with lines of longitude and latitude so that: <code>Grid-point (i, j) = (longitude(i), latitude(j))</code>  </li>
<li>Entirely irregular (topologically rectangular) grid. Specify two rank-two arrays, <code>longitude(:,:)</code> and <code>latitude(:,:)</code>. The grid may be of any form, aligned with no other projection: <code>Grid-point (i, j)</code> is taken as <code>(longitude(i, j), latitude(i, j))</code>  </li>
</ul>

<p>In all cases, single or double precision data may be used so long as all data is consistent in precision within one call. </p>

<h3>Control over the third dimension</h3>

<p>The third dimension of the data can be visualized in two (not mutually-exclusive) ways; 
firstly by assigning colours according to the value of the tird dimension, and secondly 
by using the altitude of the points as a (suitable scaled) proxy for the third dimension. 
The following optional arguments control this aspect of the visualization (both for cells and for contours)</p>

<ul>
<li>type(color) :: colormap(:): an array of colours (see Colours) which will be used for painting the various layers  </li>
<li>real, contour_values(:): an array of values which will be used to divide each layer of the third dimension. Single/double precision according to context.  </li>
<li>integer :: num<em>values: where contour</em>values is not specified, this provides that the range of the values by divided into equal sized layers such that there are this many divisors.  </li>
<li>real :: height: where this is specified, the generated visualization will vary in height as well as colour. The value of this variable will be used to as a multiplicative prefactor to scale the data before visualization.  </li>
</ul>

<p>Where no colormap is provided, one will be autogenerated with the appropriate number of levels
as calculated from the provided contour<em>values. Where no contour</em>values are provided, they are 
calculated based on the size of the colormap provided. Where neither colormap nor contour_values 
are provided, a default of 5 levels with an autogenerated colormap will be used. </p>

<h3>Subroutines</h3>

<ul>
<li><code>kmlCreateCells</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object <br />
<em>and:</em> <br />
<strong>east</strong>: <em>real</em> <em>scalar</em>: east edge of data set. <br />
<strong>west</strong>: <em>real</em> <em>scalar</em>: west edge of data set. <br />
<strong>south</strong>: <em>real</em> <em>scalar</em>: south edge of data set. <br />
<strong>north</strong>: <em>real</em> <em>scalar</em>: north edge of data set. <br />
<em>or:</em> <br />
<strong>longitude</strong>: <em>real</em> <em>array</em>: points in north-south direction where grid lines cross lines of longitude. <br />
<strong>latitude</strong>: <em>real</em> <em>array</em>: points in east-west direction where grid lines cross lines of latitude. <br />
<em>or:</em> <br />
<strong>longitude</strong>: <em>real</em> <em>matrix</em>: longitude of each point in values matrix. <br />
<strong>latitude</strong>: <em>real</em> <em>matrix</em>: latitude of each point in values matrix. <br />
<em>and:</em> <br />
<strong>values</strong>: <em>real</em> <em>matrix</em>: data values. <br />
(<strong>colormap</strong>): <em>color_t</em> <em>array</em>: colours used to describe values. <br />
(<strong>height</strong>): <em>real(sp)</em> <em>scalar</em>: where this is specified, the generated visualization will vary in height as well as colour. The value of this variable will be used to as a multiplicative prefactor to scale the data before visualization. <br />
(<strong>contour<em>values</strong>): *real(sp)* *array*: values used to contour data. <br />
(<strong>num</em>levels</strong>): <em>integer</em> <em>scalar</em>: number of data values to show. <br />
(<strong>name</strong>): <em>string</em> <em>scalar</em>: name describing the cells.  </li>
</ul>

<p>This subroutine generates a set of filled pixels over a region of the earth. </p>

<ul>
<li><code>kmlCreateContours</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object <br />
<em>and:</em> <br />
<strong>east</strong>: <em>real</em> <em>scalar</em>: east edge of data set. <br />
<strong>west</strong>: <em>real</em> <em>scalar</em>: west edge of data set. <br />
<strong>south</strong>: <em>real</em> <em>scalar</em>: south edge of data set. <br />
<strong>north</strong>: <em>real</em> <em>scalar</em>: north edge of data set. <br />
<em>or:</em> <br />
<strong>longitude</strong>: <em>real</em> <em>array</em>: points in north-south direction where grid lines cross lines of longitude. <br />
<strong>latitude</strong>: <em>real</em> <em>array</em>: points in east-west direction where grid lines cross lines of latitude. <br />
<em>or:</em> <br />
<strong>longitude</strong>: <em>real</em> <em>matrix</em>: longitude of each point in values matrix. <br />
<strong>latitude</strong>: <em>real</em> <em>matrix</em>: latitude of each point in values matrix. <br />
<em>and:</em> <br />
<strong>values</strong>: <em>real</em> <em>matrix</em>: data values. <br />
(<strong>colormap</strong>): <em>color_t</em> <em>array</em>: colours used to describe values. <br />
(<strong>height</strong>): <em>real(sp)</em> <em>scalar</em>: where this is specified, the generated visualization will vary in height as well as colour. The value of this variable will be used to as a multiplicative prefactor to scale the data before visualization. <br />
(<strong>contour<em>values</strong>): *real(sp)* *array*: values used to contour data. <br />
(<strong>num</em>levels</strong>): <em>integer</em> <em>scalar</em>: number of data values to show. <br />
(<strong>name</strong>): <em>string</em> <em>scalar</em>: name describing the cells. <br />
(<strong>lines</strong>): <em>logical</em> <em>scalar</em>: should contour lines be shown. <br />
(<strong>regions</strong>): <em>logical</em> <em>scalar</em>: should contour regions be shown.  </li>
</ul>

<p>This subroutine creates a set of contour lines.</p>

<h2>Colours</h2>

<p>KML natively handles all colours as 32-bit values, expressed as 8-digit 
hexadecimal numbers in ABGR (alpha-blue-green-red) channel order. However, 
this is not very friendly. WKML provides a nicer interface to this, and all 
WKML functions which accept colour arguments will accept them in three ways:</p>

<ul>
<li>(<strong>*color</strong>) <em>color_t</em>: the colour is passed as a wkml color_t derived type. This type is opaque and is created as described below.   </li>
<li>(<strong>*colorname</strong>) <em>string</em>: a free-text string describing a colour. WKML understands any of the approximately <a href="http://www.mcfedries.com/books/cightml/x11color.htm">700 colour names used by X11</a>.   </li>
<li>(<strong>*colorhex</strong>) <em>string(len=8)</em>: an 8-digit ABGR hexadecimal number <a href="http://code.google.com/apis/kml/documentation/kmlreference.html#color">as understood by Google Earth</a>.   </li>
</ul>

<p>A function and a subroutine are provided to maniputate the <em>color_t</em> derived type:</p>

<ul>
<li><code>kmlGetCustomColor</code>  </li>
</ul>

<p>This function takes a single argument of type <em>integer</em> or <em>string</em> and returns a <em>color_t</em> derived type. If the argument is a string the
colour is taken from the set of X11 colours, if it is an integer, i, the ith colour is selected from the X11 list.</p>

<ul>
<li><code>kmlSetCustomColor</code> <br />
<strong>myCI</strong> <em>color_t</em>: This intent(out) variable is set to the chosen colour. <br />
<strong>colorhex</strong> *string(len=8): an 8-digit ABGR hexadecimal number.  </li>
</ul>

<p>This functon takes a single argument of type <em>string(len=8)</em> representing an 8-digit AVGR hexadecimal number and returns a <em>color_t</em> derived type representing that colour.</p>

<p>Several features of wkml make use of "colour maps", arrays of the <em>color_t</em> derived type, which are used to relate numerical values to colours when showing fields of data. These are 
created and used thus:</p>

<pre><code>program colours
  use FoX_wkml
  type(color_t) :: colourmap(10)

  ! Use X11 colours from 101 to 110:
  colourmap(1:10) = kmlGetCustomColor(101:110)
  ! Except for number 5 which should be red:
  colourmap(5) = kmlGetCustomColor("indian red")
  ! And for number 6 which should be black
  call kmlSetCustomColor(colourmp(6), "00000000")

end program colours
</code></pre>

<h2>Styles</h2>

<p>Controling styling in KML can be quite complex. Most of the 
subroutines in WKML allow some control of the generated style
but they do not ptovide access to the full KML vocabulary which
allows more complex styling. In order to access the more complex
styles in KML it is necessary to create KML style maps - objects
that are defined, named with a styleURL. The styleURL is then used
to reference to the style defined by the map.</p>

<p>Styles can be created using the following three subroutines. In each 
case one argument is necessary: <em>id</em>, which must be a string (starting 
with an alphabetic letter, and containing no spaces or punctuation 
marks) which is used later on to reference the style. All other 
arguments are optional.</p>

<ul>
<li><code>kmlCreatePointStyle</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object <br />
<strong>id</strong>: <em>string</em> <em>scalar</em>: A URL for the style <br />
(<strong>scale</strong>): <em>real</em> or <em>integer</em> <em>scalar</em>: A scale factor to set the size of the image displayed at the point (note, if both are present, <strong>scale</strong> and <strong>heading</strong> must be of the same type). <br />
(<strong>color</strong>): <em>color_t</em>: Point colour as a kml color type (See Colours) <br />
(<strong>colorname</strong>): <em>string</em> <em>scalar</em>: Point colour as a name (See Colours) <br />
(<strong>colorhex</strong>): <em>string(len=8)</em> <em>scalar</em>: Point colour in hex (See Colours) <br />
(<strong>colormode</strong>): <em>string(len=6)</em> <em>scalar</em>: A string, either normal or random - if random, the colour will be randomly changed. See the <a href="http://code.google.com/apis/kml/documentation/kmlreference.html#color">KML documentation</a> <br />
(<strong>heading</strong>): <em>real</em> or <em>integer</em> <em>scalar</em>: direction to "point" the point icon in (between 0 and 360 degreesnote, if both are present, <strong>scale</strong> and <strong>heading</strong> must be of the same type). <br />
(<strong>iconhref</strong>): <em>string</em> <em>scalar</em>: URL of an icon used to draw the point (e.g. from an http server).  </li>
</ul>

<p>Creates a style that can be used for points.</p>

<ul>
<li><code>kmlCreateLineStyle</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object <br />
<strong>id</strong>: <em>string</em> <em>scalar</em>: A URL for the style <br />
(<strong>width</strong>): <em>integer</em> <em>scalar</em>: width of the line in pixels. <br />
(<strong>color</strong>): <em>color_t</em>: Point colour as a kml color type (See Colours) <br />
(<strong>colorname</strong>): <em>string</em> <em>scalar</em>: Line colour as a name (See Colours) <br />
(<strong>colorhex</strong>): <em>string(len=8)</em> <em>scalar</em>: Line colour in hex (See Colours) <br />
(<strong>colormode</strong>): <em>string(len=6)</em> <em>scalar</em>: A string, either normal or random - if random, the colour will be randomly changed. See the <a href="http://code.google.com/apis/kml/documentation/kmlreference.html#color">KML documentation</a>  </li>
</ul>

<p>Creates a style that can be used for lines.</p>

<ul>
<li><code>kmlCreatePolygonStyle</code> <br />
<strong>fx</strong>: <em>xmlf_t</em>: An XML file object <br />
<strong>id</strong>: <em>string</em> <em>scalar</em>: A URL for the style <br />
(<strong>fill</strong>): <em>logical</em> <em>scalar</em>: Should the polygon be filled? <br />
(<strong>outline</strong>): <em>logical</em> <em>scalar</em>: Should the polygon have an outline? <br />
(<strong>color</strong>): <em>color_t</em>: Point colour as a kml color type (See Colours) <br />
(<strong>colorname</strong>): <em>string</em> <em>scalar</em>: Line colour as a name (See Colours) <br />
(<strong>colorhex</strong>): <em>string(len=8)</em> <em>scalar</em>: Line colour in hex (See Colours) <br />
(<strong>colormode</strong>): <em>string(len=6)</em> <em>scalar</em>: A string, either normal or random - if random, the colour will be randomly changed. See the <a href="http://code.google.com/apis/kml/documentation/kmlreference.html#color">KML documentation</a>  </li>
</ul>

<p>Creates a style that can be used for a polygon.</p>

<h3> </h3>
</div><hr/><div class="DoX">
<a name="Debugging"/>
<h1>Debugging with FoX.</h1>

<p>Following experience integrating <code>FoX_wxml</code> into several codes, here are a few tips for debugging any problems you may encounter.</p>

<h2>Compilation problems</h2>

<p>You may encounter problems at the compiling or linking stage, with error messages along the lines of:
     'No Specific Function can be found for this Generic Function'
(exact phrasing depending on compiler, of course.)</p>

<p>If this is the case, it is possible that you have accidentally got the arguments to the offending out of order. If so, then use the keyword form of the argument to ensure correctness; that is, instead of doing:</p>

<pre><code>call cmlAddProperty(file, name, value)
</code></pre>

<p>do:</p>

<pre><code>call cmlAddProperty(xf=file, name=name, value=value)
</code></pre>

<p>This will prevent argument mismatches, and is recommended practise in any case.</p>

<h2>Runtime problems</h2>

<p>You may encounter run-time issues. FoX performs many run-time checks to ensure the validity of the resultant XML code. In so far as it is possible, FoX will either issue warnings about potential problems, or try and safely handle any errors it encounters. In both cases, warning will be output on stderr, which will hopefully help diagnose the problem.</p>

<p>Sometimes, however, FoX will encounter a problem it can do nothing about, and must stop. In all cases, it will try and write out an error message highlighting the reason, and generate a backtrace pointing to the offending line. Occasionally though, the compiler will not generate this information, and the error message will be lost.</p>

<p>If this is the case, you can either investigate the coredump to find the problem, or (if you are on a Mac) look in ~/Library/Logs/CrashReporter to find a human-readable log.</p>

<p>If this is not enlightening, or you cannot find the problem, then some of the most common issues we have encountered are listed below. Many of them are general Fortran problems, but sometimes are not easily spotted in the context of FoX.</p>

<h3>Incorrect formatting.</h3>

<p>Make sure, whenever you are writing out a real number through one of FoX's routines, and specifying a format, that the format is correct according to <a href="#StringFormatting">StringFormatting</a>. Fortran-style formats are <strong>not</strong> permitted, and will cause crashes at runtime.</p>

<h3>Array overruns</h3>

<p>If you are outputting arrays or matrices, and are doing so in the traditional Fortran style - by passing both the array and its length to the routine, like so:</p>

<pre><code> call xml_AddAttribute(xf=file, name=name, value=array, nvalue=n)
</code></pre>

<p>then if <code>n</code> is wrong, you may end up with an array overrun, and cause a crash.</p>

<p>We highly recommend wherever possible using the Fortran-90 style, like so:</p>

<pre><code> call xml_AddAttribute(xf=file, name=name, value=array)
</code></pre>

<p>where the array length will be passed automatically.</p>

<h3>Uninitialized variables</h3>

<p>If you are passing variables to FoX which have not been initialized, you may well cause a crash. This is especially true, and easy to cause if you are passing in an array which (due to a bug elsewhere) has been partly but not entirely initialized. To diagnose this, try printing out suspect variables just before passing them to FoX, and look for suspiciously wrong values.</p>

<h3>Invalid floating point numbers.</h3>

<p>If during the course of your calculation you accidentally generate Infinities, or NaNs, then passing them to any Fortran subroutine can result in a crash - therefore trying to pass them to FoX for output may result in a crash.</p>

<p>If you suspect this is happening, try printing out suspect variables before calling FoX. </p>
</div><hr/><div class="DoX">
<a name="FoX_sax"/>
<h1>SAX</h1>

<p>SAX stands for Simple API for XML, and was originally a Java API for reading XML. (Full details at <a href="http://saxproject.org">http://saxproject.org</a>). SAX implementations exist for most common modern computer languages.</p>

<p>FoX includes a SAX implementation, which translates most of the Java API into Fortran, and makes it accessible to Fortran programs, enabling them to read in XML documents in a fashion as close and familiar as possible to other languages.</p>

<p>SAX is a stream-based, event callback API. Conceptually, running a SAX parser over a document results in the parser generating events as it encounters different XML components, and sends the events to the main program, which can read them and take suitable action.</p>

<h3>Events</h3>

<p>Events are generated when the parser encounters, for example, an element opening tag, or some text, and most events carry some data with them - the name of the tag, or the contents of the text.</p>

<p>The full list of events is quite extensive, and may be seen below. For most purposes, though, it is unlikely that most users will need more than the 5 most common events, documented here.</p>

<ul>
<li><code>startDocument</code> - generated when the parser starts reading the document. No accompanying data.</li>
<li><code>endDocument</code> - generated when the parser reaches the end of the document. No accompanying data.</li>
<li><code>startElement</code> - generated by an element opening tag. Accompanied by tag name, namespace information, and a list of attributes</li>
<li><code>endElement</code> - generated by an element closing tag. Accompanied by tag name, and namespace information.</li>
<li><code>characters</code> - generated by text between tags. Accompanied by contents of text.</li>
</ul>

<p>Given these events and accompanying information, a program can extract data from an XML document.</p>

<h3>Invoking the parser.</h3>

<p>Any program using the FoX SAX parser must a) use the FoX module, and b) declare a derived type variable to hold the parser, like so:</p>

<pre><code>   use FoX_sax
   type(xml_t) :: xp
</code></pre>

<p>The FoX SAX parser then works by requiring the programmer to write a module containing subroutines to receive any of the events they are interested in, and passing these subroutines to the parser.</p>

<p>Firstly, the parser must be initialized, by passing it XML data. This can be done either by giving a filename, which the parser will manipulate, or by passing a string containing an XML document. Thus:</p>

<pre><code>  call open_xml_file(xp, "input.xml", iostat)
</code></pre>

<p>The <code>iostat</code> variable will report back any errors in opening the file.</p>

<p>Alternatively, </p>

<pre><code>  call open_xml_string(xp, XMLstring)
</code></pre>

<p>where <code>XMLstring</code> is a character variable.</p>

<p>To now run the parser over the file, you simply do:</p>

<pre><code> call parse(xp, list_of_event_handlers)
</code></pre>

<p>And once you're finished, you can close the file, and clean up the parser, with:</p>

<pre><code> call close_xml_t(xp)
</code></pre>

<h4>Options to parser</h4>

<p>It is unlikely that most users will need to operate any of these options, but the following are available for use; all are optional boolean arguments to <code>parse</code>.</p>

<ul>
<li><p><code>namespaces</code> <br />
Does namespace processing occur? Default is <code>.true.</code>, and if on, then any non-namespace-well-formed documents will be rejected, and namespace URI resolution will be performed according to the version of XML in question. If off, then documents will be processed without regard for namespace well-formedness, and no namespace URI resolution will be performed.</p></li>
<li><p><code>namespace_prefixes</code>
Are <code>xmlns</code> attributes reported through the SAX parser? Default is <code>.false.</code>; all such attributes are removed by the parser, and transparent namespace URI resolution is performed. If on, then such attributes will be reported, and treated according to the value of <code>xmlns-uris</code> below. (If <code>namespaces</code> is false, this flag has no effect)</p></li>
<li><p><code>validate</code>
Should validation be performed? Default is <code>.false.</code>, no validation checks are made, and the influence of the DTD on the XML Infoset is ignored. (Ill-formed DTD's will still cause fatal errors, of course.) If <code>.true.</code>, then validation will be performed, and the Infoset modified accordingly.</p></li>
<li><p><code>xmlns_uris</code>
Should <code>xmlns</code> attributes have a namespace of <code>http://www.w3.org/2000/xmlns/</code>? Default is <code>.false.</code>. If such attributes are reported, they have no namespace. If <code>.true.</code> then they are supplied with the appropriate namespace. (if <code>namespaces</code> or <code>namespace-prefixes</code> are <code>.false.</code>, then this flag has no effect.)</p></li>
</ul>

<h3>Receiving events</h3>

<p>To receive events, you must construct a module containing event handling subroutines. These are subroutines of a prescribed form - the input &amp; output is predetermined by the requirements of the SAX interface, but the body of the subroutine is up to you.</p>

<p>The required forms are shown in the API documentation below, but here are some simple examples.</p>

<p>To receive notification of character events, you must write a subroutine which takes as input one string, which will contain the characters received. So:</p>

<pre><code>module event_handling
  use FoX_sax
contains

  subroutine characters_handler(chars)
    character(len=*), intent(in) :: chars

    print*, chars
  end subroutine
end module
</code></pre>

<p>That does very little - it simply prints out the data it receives. However, since the subroutine is in a module, you can save the data to a module variable, and manipulate it elsewhere; alternatively you can choose to call other subroutines based on the input.</p>

<p>So, a complete program which reads in all the text from an XML document looks like this:</p>

<pre><code>module event_handling
  use FoX_sax
contains

  subroutine characters_handler(chars)
    character(len=*), intent(in) :: chars

    print*, chars
  end subroutine
end module

program XMLreader
  use FoX_sax
  use event_handling
  type(xml_t) :: xp
  call open_xml_file(xp, 'input.xml')
  call parse(xp, characters_handler=characters_handler)
  call close_xml_t(xp)
end program
</code></pre>

<h3>Attribute dictionaries.</h3>

<p>The other likely most common event is the startElement event. Handling this involves writing a subroutine which takes as input three strings (which are the local name, namespace URI, and fully qualified name of the tag) and a dictionary of attributes. </p>

<p>An attribute dictionary is essentially a set of key:value pairs - where the key is the attributes name, and the value is its value. (When considering namespaces, each attribute also has a URI and localName.)</p>

<p>Full details of all the dictionary-manipulation routines are given in <a href="#AttributeDictionaries">AttributeDictionaries</a>, but here we shall show the most common.</p>

<ul>
<li><p><code>getLength(dictionary)</code> - returns the number of entries in the dictionary (the number of attributes declared)</p></li>
<li><p><code>hasKey(dictionary, qName)</code> (where <code>qName</code> is a string) returns <code>.true.</code> or <code>.false.</code> depending on whether an attribute named <code>qName</code> is present.</p></li>
<li><p><code>hasKey(dictionary, URI, localname)</code> (where <code>URI</code> and <code>localname</code> are strings) returns <code>.true.</code> or <code>.false.</code> depending on whether an attribute with the appropriate <code>URI</code> and <code>localname</code> is present.</p></li>
<li><p><code>getQName(dictionary, i)</code> (where <code>i</code> is an integer) returns a string containing the key of the <code>i</code>th dictionary entry (ie, the name of the <code>i</code>th attribute.</p></li>
<li><p><code>getValue(dictionary, i)</code> (where <code>i</code> is an integer) returns a string containing the value of the <code>i</code>th dictionary entry (ie the value of the <code>i</code>th attribute.</p></li>
<li><p><code>getValue(dictionary, URI, localname)</code> (where <code>URI</code> and <code>localname</code> are strings) returns a string containing the value of the attribute with the appropriate <code>URI</code> and <code>localname</code> (if it is present)</p></li>
</ul>

<p>So, a simple subroutine to receive a startElement event would look like:</p>

<pre><code>module event_handling

contains

 subroutine startElement_handler(URI, localname, name,attributes)
   character(len=*), intent(in)   :: URI  
   character(len=*), intent(in)   :: localname
   character(len=*), intent(in)   :: name 
   type(dictionary_t), intent(in) :: attributes

   integer :: i

   print*, name

   do i = 1, getLength(attributes)
      print*, getQName(attributes, i), '=', getValue(attributes, i)
   enddo

  end subroutine startElement_handler
end module

program XMLreader
 use FoX_sax
 use event_handling
 type(xml_t) :: xp
 call open_xml_file(xp, 'input.xml')
 call parse(xp, startElement_handler=startElement_handler)
 call close_xml_t(xp)
end program
</code></pre>

<p>Again, this does nothing but print out the name of the element, and the names and values of all of its attributes. However, by using module variables, or calling other subroutines, the data could be manipulated further.</p>

<h3>Error handling</h3>

<p>The SAX parser detects all XML well-formedness errors (and optionally validation errors). By default, when it encounters an error, it will simply halt the program with a suitable error message. However, it is possible to pass in an error handling subroutine if some other behaviour is desired - for example it may be nice to report the error to the user, finish parsing, and carry on with some other task.</p>

<p>In any case, once an error is encountered, the parser will finish. There is no way to continue reading past an error. (This means that all errors are treated as fatal errors, in the terminology of the XML standard).</p>

<p>An error handling subroutine works in the same way as any other event handler, with the event data being an error message. Thus, you could write:</p>

<pre><code>subroutine fatalError_handler(msg)
  character(len=*), intent(in) :: msg

  print*, "The SAX parser encountered an error:"
  print*, msg
  print*, "Never mind, carrying on with the rest of the calcaulation."
end subroutine
</code></pre>

<h3>Stopping the parser.</h3>

<p>The parser can be stopped at any time. Simply do (from within one of the callback functions).</p>

<pre><code>call stop_parser(xp)
</code></pre>

<p>(where <code>xp</code> is the XML parser object). The current callback function will be completed, then the parser will be stopped, and control will return to the main program, the parser having finished.</p>

<hr />

<h2>Full API</h2>

<h3>Derived types</h3>

<p>There is one derived type, <code>xml_t</code>. This is entirely opaque, and is used as a handle for the parser.</p>

<h3>Subroutines</h3>

<p>There are four subroutines:</p>

<ul>
<li><code>open_xml_file <br />
type(xml_t), intent(inout) :: xp <br />
character(len=*), intent(in) :: string <br />
integer, intent(out), optional :: iostat</code></li>
</ul>

<p>This opens a file. <code>xp</code> is initialized, and prepared for parsing. <code>string</code> must contain the name of the file to be opened. <code>iostat</code> reports on the success of opening the file. A value of <code>0</code> indicates success.</p>

<ul>
<li><p><code>open_xml_string <br />
type(xml_t), intent(inout) :: xpi <br />
character(len=*), intent(in) :: string</code></p>

<p>This prepares to parse a string containing XML data. <code>xp</code> is initialized. <code>string</code> must contain the XML data.</p></li>
<li><p><code>close_xml_t <br />
type(xml_t), intent(inout) :: xp</code></p></li>
</ul>

<p>This closes down the parser (and closes the file, if input was coming from a file.) <code>xp</code> is left uninitialized, ready to be used again if necessary.</p>

<ul>
<li><p><code>parse <br />
type(xml_t), intent(inout) :: xp <br />
external :: list of event handlers <br />
logical, optional, intent(in) :: validate</code></p>

<p>This tells <code>xp</code> to start parsing its document. </p></li>
</ul>

<p>(<em>Advanced: See above for the list of options that the <code>parse</code> subroutine may take.</em>)</p>

<p>The full list of event handlers is in the next section. To use them, the interface must be placed in a module, and the body of the subroutine filled in as desired; then it should be specified as an argument to <code>parse</code> as: <br />
  <code>name_of_event_handler = name_of_user_written_subroutine</code> <br />
Thus a typical call to <code>parse</code> might look something like:</p>

<pre><code>  call parse(xp, startElement_handler = mystartelement, endElement_handler = myendelement, characters_handler = mychars)
</code></pre>

<p>where <code>mystartelement</code>, <code>myendelement</code>, and <code>mychars</code> are all  subroutines written by you according to the interfaces listed below.</p>

<hr />

<h2>Callbacks.</h2>

<p>All of the callbacks specified by SAX 2 are implemented. Documentation of the SAX 2 interfaces is available in the JavaDoc at <a href="http://sax_project.org">http://saxproject.org</a>, but as the interfaces needed adjustment for Fortran, they are listed here.</p>

<p>For documentation on the meaning of the callbacks and of their arguments, please refer to the Java SAX documentation.</p>

<ul>
<li><code>characters_handler <br />
  subroutine characters_handler(chunk) <br />
    character(len=*), intent(in) :: chunk <br />
  end subroutine characters_handler</code></li>
</ul>

<p>Triggered when some character data is read from between tags. </p>

<p>NB Note that <em>all</em> character data is reported, including whitespace. Thus you will probably get a lot of empty <code>characters</code> events in a typical XML document.</p>

<p>NB Note also that it is not required that a single chunk of character data all come as one event - it may come as multiple consecutive events. You should concatenate the results of subsequent character events before processing.</p>

<ul>
<li><code>endDocument_handler <br />
  subroutine endDocument_handler() <br />
  end subroutine endDocument_handler</code></li>
</ul>

<p>Triggered when the parser reaches the end of the document.</p>

<ul>
<li><code>endElement_handler <br />
  subroutine endElement_handler(namespaceURI, localName, name) <br />
    character(len=*), intent(in)     :: namespaceURI <br />
    character(len=*), intent(in)     :: localName <br />
    character(len=*), intent(in)     :: name <br />
  end subroutine endElement_handler</code></li>
</ul>

<p>Triggered by a closing tag.</p>

<ul>
<li><code>endPrefixMapping_handler <br />
  subroutine endPrefixMapping_handler(prefix) <br />
    character(len=*), intent(in) :: prefix <br />
  end subroutine endPrefixMapping_handler</code></li>
</ul>

<p>Triggered when a namespace prefix mapping goes out of scope.</p>

<ul>
<li><code>ignorableWhitespace <br />
  subroutine ignorableWhitespace_handler(chars) <br />
    character(len=*), intent(in) :: chars <br />
  end subroutine ignorableWhitespace_handler</code></li>
</ul>

<p>Triggered when whitespace is encountered within an element declared as having no PCDATA. (Only active in validating mode.)</p>

<ul>
<li><code>processingInstruction_handler <br />
  subroutine processingInstruction_handler(name, content) <br />
    character(len=*), intent(in)     :: name <br />
    character(len=*), intent(in)     :: content <br />
  end subroutine processingInstruction_handler</code></li>
</ul>

<p>Triggered by a Processing Instruction</p>

<ul>
<li><code>skippedEntity_handler <br />
  subroutine skippedEntity_handler(name) <br />
    character(len=*), intent(in) :: name <br />
  end subroutine skippedEntity_handler</code></li>
</ul>

<p>Triggered when either an external entity, or an undeclared entity, is skipped.</p>

<ul>
<li><code>startDocument_handler <br />
  subroutine startDocument_handler() <br />
  end subroutine startDocument_handler</code></li>
</ul>

<p>Triggered when the parser starts reading the document.</p>

<ul>
<li><code>startElement_handler <br />
  subroutine startElement_handler(namespaceURI, localName, name, attributes) <br />
    character(len=*), intent(in)     :: namespaceUri <br />
    character(len=*), intent(in)     :: localName <br />
    character(len=*), intent(in)     :: name <br />
    type(dictionary_t), intent(in)   :: attributes <br />
  end subroutine startElement_handler</code></li>
</ul>

<p>Triggered when an opening tag is encountered. (see LINK for documentation on handling attribute dictionaries.</p>

<ul>
<li><code>startPrefixMapping_handler <br />
  subroutine startPrefixMapping_handler(namespaceURI, prefix) <br />
    character(len=*), intent(in) :: namespaceURI <br />
    character(len=*), intent(in) :: prefix <br />
  end subroutine startPrefixMapping_handler</code></li>
</ul>

<p>Triggered when a namespace prefix mapping start.</p>

<ul>
<li><code>notationDecl_handler <br />
  subroutine notationDecl_handler(name, publicId, systemId) <br />
    character(len=*), intent(in) :: name <br />
    character(len=*), intent(in) :: publicId <br />
    character(len=*), intent(in) :: systemId <br />
  end subroutine notationDecl_handler</code></li>
</ul>

<p>Triggered when a NOTATION declaration is made in the DTD</p>

<ul>
<li><code>unparsedEntityDecl_handler <br />
  subroutine unparsedEntityDecl_handler(name, publicId, systemId, notation) <br />
    character(len=*), intent(in) :: name <br />
    character(len=*), intent(in) :: publicId <br />
    character(len=*), intent(in) :: systemId <br />
    character(len=*), intent(in) :: notation <br />
  end subroutine unparsedEntityDecl_handler</code></li>
</ul>

<p>Triggered when an unparsed entity is declared</p>

<ul>
<li><code>error_handler <br />
  subroutine error_handler(msg) <br />
    character(len=*), intent(in)     :: msg <br />
  end subroutine error_handler</code></li>
</ul>

<p>Triggered when a <a href="http://www.w3.org/TR/REC-xml/#dt-error">error</a> is encountered in parsing. Parsing will continue after this event.</p>

<ul>
<li><code>fatalError_handler <br />
  subroutine fatalError_handler(msg) <br />
    character(len=*), intent(in)     :: msg <br />
  end subroutine fatalError_handler</code></li>
</ul>

<p>Triggered when a <a href="http://www.w3.org/TR/REC-xml/#dt-fatal">fatal error</a> is encountered in parsing. Parsing will cease after this event.</p>

<ul>
<li><code>warning_handler <br />
  subroutine warning_handler(msg) <br />
    character(len=*), intent(in)     :: msg <br />
  end subroutine warning_handler</code></li>
</ul>

<p>Triggered when a parser warning is generated. Parsing will continue after this event.</p>

<ul>
<li><code>attributeDecl_handler <br />
  subroutine attributeDecl_handler(eName, aName, type, mode, value) <br />
    character(len=*), intent(in) :: eName <br />
    character(len=*), intent(in) :: aName <br />
    character(len=*), intent(in) :: type <br />
    character(len=*), intent(in) :: mode <br />
    character(len=*), intent(in) :: value <br />
  end subroutine attributeDecl_handler</code></li>
</ul>

<p>Triggered when an attribute declaration is encountered in the DTD.</p>

<ul>
<li><code>elementDecl_handler <br />
  subroutine elementDecl_handler(name, model) <br />
    character(len=*), intent(in) :: name <br />
    character(len=*), intent(in) :: model <br />
  end subroutine elementDecl_handler</code></li>
</ul>

<p>Triggered when an element declaration is enountered in the DTD.</p>

<ul>
<li><code>externalEntityDecl_handler <br />
  subroutine externalEntityDecl_handler(name, publicId, systemId) <br />
    character(len=*), intent(in) :: name <br />
    character(len=*), intent(in) :: publicId <br />
    character(len=*), intent(in) :: systemId <br />
  end subroutine externalEntityDecl_handler</code></li>
</ul>

<p>Triggered when a parsed external entity is declared in the DTD.</p>

<ul>
<li><code>internalEntityDecl_handler <br />
  subroutine internalEntityDecl_handler(name, value) <br />
    character(len=*), intent(in) :: name <br />
    character(len=*), intent(in) :: value <br />
  end subroutine internalEntityDecl_handler</code></li>
</ul>

<p>Triggered when an internal entity is declared in the DTD.</p>

<ul>
<li><code>comment_handler <br />
  subroutine comment_handler(comment) <br />
    character(len=*), intent(in) :: comment <br />
  end subroutine comment_handler</code></li>
</ul>

<p>Triggered when a comment is encountered.</p>

<ul>
<li><code>endCdata_handler <br />
  subroutine endCdata_handler() <br />
  end subroutine endCdata_handler</code></li>
</ul>

<p>Triggered by the end of a CData section.</p>

<ul>
<li><code>endDTD_handler <br />
  subroutine endDTD_handler() <br />
  end subroutine endDTD_handler</code></li>
</ul>

<p>Triggered by the end of a DTD.</p>

<ul>
<li><code>endEntity_handler <br />
  subroutine endEntity_handler(name) <br />
    character(len=*), intent(in) :: name <br />
  end subroutine endEntity_handler</code></li>
</ul>

<p>Triggered at the end of entity expansion.</p>

<ul>
<li><code>startCdata_handler <br />
  subroutine startCdata_handler() <br />
  end subroutine startCdata_handler</code></li>
</ul>

<p>Triggered by the start of a CData section.</p>

<ul>
<li><code>startDTD_handler <br />
  subroutine startDTD_handler(name, publicId, systemId) <br />
    character(len=*), intent(in) :: name <br />
    character(len=*), intent(in) :: publicId <br />
    character(len=*), intent(in) :: systemId <br />
  end subroutine startDTD_handler</code></li>
</ul>

<p>Triggered by the start of a DTD section.</p>

<ul>
<li><code>startEntity_handler <br />
  subroutine startEntity_handler(name) <br />
    character(len=*), intent(in) :: name <br />
  end subroutine startEntity_handler</code></li>
</ul>

<p>Triggered by the start of entity expansion.</p>

<hr />

<h3>Exceptions.</h3>

<p>The FoX SAX implementation implements all of XML 1.0 and 1.1; all of XML Namespaces 1.0 and 1.1; xml:id and xml:base.</p>

<p>Although FoX tries very hard to  work to the letter of the XML and SAX standards, it falls short in a few areas.</p>

<ul>
<li><p>FoX will only process documents consisting of nothing but US-ASCII data. It will accept documents labelled with any single byte character set which is identical to US-ASCII in its lower 7 bits (for example, any of the ISO-8859 charsets, or UTF-8) but an error will be generated as soon as any character outside US-ASCII is encountered. (This includes non-ASCII characters present only be character entity reference)</p></li>
<li><p>As a corollary, UTF-16 documents of any endianness will also be rejected.</p></li>
</ul>

<p>(It is impossible to implement IO of non-ASCII documents in a portable fashion using standard Fortran 95, and it is impossible to handle non-ASCII data internally using standard Fortran strings. A fully unicode-capable FoX version is under development, but requires Fortran 2003. Please enquire for further details if you're interested.)</p>

<ul>
<li>FoX has no network capabilities. Therefore, when external entities are referenced, any entities not available on the local filesystem will not be accessed (specifically, any entities whose URI reference includes a scheme component, where that scheme is not <code>file</code>, will be skipped)</li>
</ul>

<p>Beyond this, any aspects of the listed XML standards to which FoX fails to do justice to are bugs.</p>

<hr />

<h3>What of Java SAX 2 is not included in FoX?</h3>

<p>The difference betweek Java &amp; Fortran means that none of the SAX APIs can be copied directly. However, FoX offers data types, subroutines, and interfaces covering most of the facilities offered by SAX. Where it does not, this is mentioned here.</p>

<p>org.sax.xml:</p>

<ul>
<li>Querying/setting of feature flags/property values for the XML parser. The effect of a subset of these may be accessed by options to the <code>parse</code> subroutine.</li>
<li>XML filters - Java SAX makes it possible to write filters to intercept the
flow of events. FoX does not support this.  </li>
<li>Entity resolution - SAX 2 exports an interface to the application for entity resolution, but FoX does not - all entities are resolved within the parser.</li>
<li>Locator - SAX 2 offers an interface to export information regarding object locations within the document, FoX does not.  </li>
<li>XMLReader - FoX only offers the parse() method - no other methods really make sense in Fortran.  </li>
<li>AttributeList/DocumentHandler/Parser - FoX only offers namespace aware attributes, not the pre-namespace SAX-1 versions.  </li>
</ul>

<p>org.sax.xml.ext:</p>

<ul>
<li>EntityResolver2 - not implemented  </li>
<li>Locator2 - not implemented  </li>
</ul>

<p>org.sax.xml.helpers:</p>

<ul>
<li>None of these helper methods are implemented.</li>
</ul>
</div><hr/><div class="DoX">
<a name="AttributeDictionaries"/>
<h1>Attributes dictionaries.</h1>

<p>When parsing XML using the FoX SAX module, attributes are returned contained within a dictionary object.</p>

<p>This dictionary object implements all the methods described by the SAX interfaces Attributes and Attributes2. Full documentation is available from the SAX Javadoc, but is reproduced here for ease of reference.</p>

<p>All of the attribute dictionary objects and functions are exported through FoX_sax - you must USE the module to enable them. The dictionary API is described here.</p>

<p>An attribute dictionary consists of a list of entries, one for each attribute. The entries all have the following pieces of data:</p>

<ul>
<li>qName - the attribute's full name  </li>
<li>value - the attribute's value</li>
</ul>

<p>and for namespaced attributes:</p>

<ul>
<li>uri - the namespace URI (if any) of the attribute  </li>
<li>localName - the local name of the attribute</li>
</ul>

<p>In addition, the following pieces of data will be picked up from a DTD if present:</p>

<ul>
<li>declared - is the attribute declared in the DTD?  </li>
<li>specified - is this instance of the attribute specified in the XML document, or is it a default from the DTD?  </li>
<li>type - the type of the attribute (if declared)</li>
</ul>

<hr />

<h2>Derived types</h2>

<p>There is one derived type of interest, <code>dictionary_t</code>.</p>

<p>It is opaque - that is, it should only be manipulated through the functions described here.</p>

<h2>Functions</h2>

<h3>Inspecting the dictionary</h3>

<ul>
<li><code>getLength <br />
type(dictionary_t), intent(in) :: dict</code></li>
</ul>

<p>Returns an integer with the length of the dictionary, <em>ie</em> the number of dictionary entries.</p>

<ul>
<li><code>hasKey <br />
type(dictionary_t), intent(in) :: dict <br />
character(len=*), intent(in) :: key</code></li>
</ul>

<p>Returns a logical value according to whether the dictionary contains an attribute named <code>key</code> or not.</p>

<ul>
<li><code>hasKey <br />
type(dictionary_t), intent(in) :: dict <br />
character(len=*), intent(in) :: uri <br />
character(len=*), intent(in) :: localname</code></li>
</ul>

<p>Returns a logical value according to whether the dictionary contains an attribute with the correct <code>URI</code> and <code>localname</code>.</p>

<h3>Retrieving data from the dictionary</h3>

<ul>
<li><code>getQName <br />
type(dictionary_t), intent(in) :: dict <br />
integer, intent(in) :: i</code></li>
</ul>

<p>Return the full name of the <code>i</code>th dictionary entry.</p>

<ul>
<li><code>getValue <br />
type(dictionary_t), intent(in) <br />
integer, intent(in) :: i</code></li>
</ul>

<p>If an integer is passed in - the value of the <code>i</code>th attribute. </p>

<ul>
<li><code>getValue <br />
type(dictionary_t), intent(in) <br />
character(len=*), intent(in) :: qName</code></li>
</ul>

<p>If a single string is passed in, the value of the attribute with that name.</p>

<ul>
<li><code>getValue <br />
type(dictionary_t), intent(in) <br />
character(len=*), intent(in) :: uri, localname</code></li>
</ul>

<p>If two strings are passed in, the value of the attribute with that uri and localname.</p>

<ul>
<li><code>getURI <br />
type(dictionary_t), intent(in) <br />
integer, intent(in) :: i</code></li>
</ul>

<p>Returns a string containing the nsURI of the <code>i</code>th attribute.</p>

<ul>
<li><code>getlocalName <br />
type(dictionary_t), intent(in) <br />
integer, intent(in) :: i</code></li>
</ul>

<p>Returns a string containing the localName of the <code>i</code>th attribute.</p>

<h3>DTD-driven functions</h3>

<p>The following functions are only of interest if you are using DTDs.</p>

<ul>
<li><code>getType 
type(dictionary_t), intent(in) <br />
integer, intent(in), optional :: i</code></li>
</ul>

<p>If an integer is passed in, returns the type of the <code>i</code>th attribute.</p>

<ul>
<li><code>getType <br />
type(dictionary_t), intent(in) <br />
character(len=*), intent(in) :: qName</code></li>
</ul>

<p>If a single string is passed in, returns the type of the attribute with that QName.</p>

<ul>
<li><code>getType <br />
type(dictionary_t), intent(in) <br />
character(len=*), intent(in) :: uri <br />
character(len=*), intent(in) :: localName</code></li>
</ul>

<p>If a single string is passed in, returnsthe type of the attribute with that {uri,localName}.</p>

<ul>
<li><code>isDeclared <br />
type(dictionary_t), intent(in) <br />
integer, intent(in), optional :: i</code></li>
</ul>

<p>If an integer is passed in, returns false unless the <code>i</code>th attribute is declared in the DTD.</p>

<ul>
<li><code>isDeclared 
type(dictionary_t), intent(in) <br />
character(len=*), intent(in) :: qName</code></li>
</ul>

<p>If a single string is passed in, returns false unless the attribute with that QName is declared in the DTD.</p>

<ul>
<li><code>isDeclared <br />
type(dictionary_t), intent(in) <br />
character(len=*), intent(in) :: uri <br />
character(len=*), intent(in) :: localName</code></li>
</ul>

<p>If a single string is passed in, returns false unless the attribute with that {uri,localName} is declared in the DTD.</p>

<ul>
<li><code>isSpecified <br />
type(dictionary_t), intent(in) <br />
integer, intent(in), optional :: i</code></li>
</ul>

<p>If an integer is passed in, returns true unless the <code>i</code>th attribute is a default value from the DTD.</p>

<ul>
<li><code>isSpecified 
type(dictionary_t), intent(in) <br />
character(len=*), intent(in) :: qName</code></li>
</ul>

<p>If a single string is passed in, returns true unless the attribute with that QName is a default value from the DTD.</p>

<ul>
<li><code>isSpecified <br />
type(dictionary_t), intent(in) <br />
character(len=*), intent(in) :: uri <br />
character(len=*), intent(in) :: localName</code></li>
</ul>

<p>If a single string is passed in, returns true unless the attribute with that {uri,localName} is a default value from the DTD.</p>
</div><hr/><div class="DoX">
<a name="FoX_dom"/>
<h1>DOM</h1>

<h2>Overview</h2>

<p>The FoX DOM interface exposes an API as specified by the W3C DOM Working group.</p>

<p>FoX implements essentially all of DOM Core Levels 1 and 2, (there are a number of minor exceptions which are listed below) and a substantial portion of DOM Core Level 3.</p>

<ul>
<li><a href="#DomQuickOverview">Quick overview of how to map the DOM interface to Fortran</a>  </li>
<li><a href="#DomDetailedInterface">More detailed explanation of Fortran interface</a>  </li>
<li><a href="#DomUtilityFunctions">Additional (non-DOM) utility functions</a>  </li>
<li><a href="#DomString">String handling</a>  </li>
<li><a href="#DomException">Exception handling</a>  </li>
<li><a href="#DomLiveNodelists">Live nodelists</a>  </li>
<li><a href="#DomConfiguration">DOM Configuration</a>  </li>
<li><a href="#DomMiscellanea">Miscellanea</a></li>
</ul>

<h2>Interface Mapping</h2>

<p><a name="DomQuickOverview"/></p>

<p>FoX implements all objects and methods mandated in DOM Core Level 1 and 2. (A listing of supported DOM Core Level 3 interfaces is given below.)</p>

<p>In all cases, the mapping from DOM interface to Fortran implementation is as follows:</p>

<ol>
<li>All DOM objects are available as Fortran types, and should be referenced only as pointers (though see 7 and 8 below). Thus, to use a Node, it must be declared first as: <br />
<code>type(Node), pointer :: aNode</code></li>
<li>A flat (non-inheriting) object hierarchy is used. All DOM objects which inherit from Node are represented as Node types.   </li>
<li>All object method calls are modelled as functions or subroutines with the same name, whose first argument is the object. Thus: <br />
<code>aNodelist = aNode.getElementsByTagName(tagName)</code> <br />
should be converted to Fortran as: <br />
<code>aNodelist =&gt; getElementsByTagName(aNode, tagName)</code>  </li>
<li>All object method calls whose return type is void are modelled as subroutines. Thus: <br />
<code>aNode.normalize()</code> <br />
becomes
<code>call normalize(aNode)</code>   </li>
<li>All object attributes are modelled as a pair of get/set calls (or only get where the attribute is readonly), with the naming convention being merely to prepend get or set to the attribute name. Thus: <br />
<code>name = node.nodeName</code> <br />
<code>node.nodeValue = string</code> <br />
should be converted to Fortran as <br />
<code>name = getnodeName(node)</code> <br />
<code>call setnodeValue(string)</code>  </li>
<li>Where an object method or attribute getter returns a DOM object, the relevant Fortran function must always be used as a pointer function. Thus: <br />
<code>aNodelist =&gt; getElementsByTagName(aNode, tagName)</code>  </li>
<li>No special DOMString object is used - all string operations are done on the standard Fortran character strings, and all functions that return DOMStrings return Fortran character strings.</li>
<li>Exceptions are modelled by every DOM subroutine/function allowing an optional additional argument, of type DOMException. For further information see (#DOM Exceptions) below. </li>
</ol>

<h3>String handling</h3>

<p><a name="DomString"/></p>

<p>The W3C DOM requires that a <code>DOMString</code> object exist, capable of holding Unicode strings; and that all DOM functions accept and emit DOMString objects when string data is to be transferred.</p>

<p>FoX does not follow this model. Since (as mentioned elsewhere) it is impossible to perform Unicode I/O in standard Fortran, it would be obtuse to require users to manipulate additional objects merely to transfer strings. Therefore, wherever the DOM mandates use of a <code>DOMString</code>, FoX merely uses standard Fortran character strings.</p>

<p>All functions or subroutines which expect DOMString input arguments should be used with normal character strings. <br />
All functions which should return DOMString objects will return Fortran character strings.</p>

<h3>Using the FoX DOM library.</h3>

<p>All functions are exposed through the module <code>FoX_DOM</code>. <code>USE</code> this in your program:</p>

<pre><code>program dom_example

  use FoX_DOM
  type(Node) :: myDoc

  myDoc =&gt; parseFile("fileIn.xml")
  call serialize(myDoc, "fileOut.xml")
end program dom_example
</code></pre>

<h2>Documenting DOM functions</h2>

<p><a name="DomDetailedInterface"/></p>

<p>This manual will not exhaustively document the functions available through the <code>Fox_DOM</code> interface. Primary documentation may be found in the W3C DOM specifications:`</p>

<ul>
<li><a href="http://www.w3.org/TR/REC-DOM-Level-1/">DOM Core Level 1</a></li>
<li><a href="http://www.w3.org/TR/DOM-Level-2-Core/">DOM Core Level 2</a></li>
<li><a href="http://www.w3.org/TR/DOM-Level-3-Core/">DOM Core Level 3</a></li>
</ul>

<p>The systematic rules for translating the DOM interfaces to Fortran are given in the previous section. For completeness, though, there is a list here. The W3C specifications should be consulted for the use of each.</p>

<p>DOMImplementation: <br />
<code>type(DOMImplementation), pointer</code></p>

<ul>
<li><code>hasFeature(impl, feature, version)</code>  </li>
<li><code>createDocumentType(impl, qualifiedName, publicId, systemId)</code>  </li>
<li><code>createDocument(impl, qualifiedName, publicId, systemId)</code>  </li>
</ul>

<p>Document: 
<code>type(Node), pointer</code></p>

<ul>
<li><code>getDocType(doc)</code></li>
<li><code>getImplementation(doc)</code>    </li>
<li><code>getDocumentElement(doc)</code>    </li>
<li><code>createElement(doc, tagname)</code>    </li>
<li><code>createDocumentFragment(doc)</code>    </li>
<li><code>createTextNode(doc, data)</code>    </li>
<li><code>createComment(doc, data)</code>    </li>
<li><code>createCDataSection(doc, data)</code>    </li>
<li><code>createProcessingInstruction(doc, target, data)</code>    </li>
<li><code>createAttribute(doc, name)</code>    </li>
<li><code>createEntityReference(doc, name)</code>    </li>
<li><code>getElementsByTagName(doc, tagname)</code>    </li>
<li><code>importNode(doc, importedNode, deep)</code>    </li>
<li><code>createElementNS(doc, namespaceURI, qualifiedName)</code>    </li>
<li><code>createAttributeNS(doc, namespaceURI, qualifiedName)</code>    </li>
<li><code>getElementsByTagNameNS(doc, namespaceURI, qualifiedName)</code>    </li>
<li><code>getElementById(doc, elementId)</code></li></li>
</ul>

<p>Node: <br />
<code>type(Node), pointer</code></p>

<ul>
<li><code>getNodeName(arg)</code>    </li>
<li><code>getNodeValue(arg)</code>    </li>
<li><code>setNodeValue(arg, value)</code>    </li>
<li><code>getNodeType(arg)</code>    </li>
<li><code>getParentNode(arg)</code>    </li>
<li><code>getChildNodes(arg)</code>    </li>
<li><code>getFirstChild(arg)</code>    </li>
<li><code>getLastChild(arg)</code>    </li>
<li><code>getPreviousSibling(arg)</code>    </li>
<li><code>getNextSibling(arg)</code>    </li>
<li><code>getAttributes(arg)</code>    </li>
<li><code>getOwnerDocument(arg)</code>    </li>
<li><code>insertBefore(arg, newChild, refChild)</code>    </li>
<li><code>replaceChild(arg, newChild, refChild)</code>    </li>
<li><code>removeChild(arg, oldChild)</code>    </li>
<li><code>appendChild(arg, newChild)</code>    </li>
<li><code>hasChildNodes(arg)</code>  </li>
<li><code>cloneNode(arg, deep)</code>  </li>
<li><code>normalize</code>    </li>
<li><code>isSupported(arg, feature, version)</code>    </li>
<li><code>getNamespaceURI(arg)</code>    </li>
<li><code>getPrefix(arg)</code>    </li>
<li><code>setPrefix(arg, prefix)</code>  </li>
<li><code>getLocalName(arg)</code>    </li>
<li><code>hasAttributes(arg)</code> <br />
</ul></li>
</ul>

<p>NodeList: <br />
<code>type(NodeList), pointer</code></p>

<ul>
<li><code>item(arg, index)</code>    </li>
<li><code>getLength(arg)</code>  </li>
</ul>

<p>NamedNodeMap: <br />
<code>type(NamedNodeMap), pointer</code></p>

<ul>
<li><code>getNamedItem(map, name)</code>    </li>
<li><code>setNamedItem(map, arg)</code>    </li>
<li><code>removeNamedItem(map, name)</code>    </li>
<li><code>item(map, index)</code>    </li>
<li><code>getLength(map)</code>    </li>
<li><code>getNamedItemNS(map, namespaceURI, qualifiedName)</code>    </li>
<li><code>setNamedItemNS(map, arg)</code>    </li>
<li><code>removeNamedItemNS(map, namespaceURI, qualifiedName)</code>    </li>
</ul>

<p>CharacterData: <br />
<code>type(Node), pointer</code></p>

<ul>
<li><code>getData(np)</code>    </li>
<li><code>setData(np, data)</code>    </li>
<li><code>getLength(np)</code>    </li>
<li><code>substringData(np, offset, count)</code>    </li>
<li><code>appendData(np, arg)</code>    </li>
<li><code>deleteData(np, offset, count)</code>    </li>
<li><code>replaceData(np, offset, count, arg)</code></li>
</ul>

<p>Attr: <br />
<code>type(Node), pointer</code></p>

<ul>
<li><code>getName(np)</code>    </li>
<li><code>getSpecified(np)</code>    </li>
<li><code>getValue(np)</code>    </li>
<li><code>setValue(np, value)</code>    </li>
<li><code>getOwnerElement(np)</code></li>
</ul>

<p>Element: <br />
<code>type(Node), pointer</code></p>

<ul>
<li><code>getTagName(np)</code>    </li>
<li><code>getAttribute(np, name)</code>    </li>
<li><code>setAttribute(np, name, value)</code>    </li>
<li><code>removeAttribute(np, name)</code>    </li>
<li><code>getAttributeNode(np, name)</code>    </li>
<li><code>setAttributeNode(np, newAttr)</code>    </li>
<li><code>removeAttributeNode(np, oldAttr)</code>    </li>
<li><code>getElementsByTagName(np, name)</code>  </li>
<li><code>getAttributeNS(np, namespaceURI, qualifiedName)</code>    </li>
<li><code>setAttributeNS(np, namespaceURI, qualifiedName, value)</code>    </li>
<li><code>removeAttributeNS(np, namespaceURI, qualifiedName)</code>    </li>
<li><code>getAttributeNode(np, namespaceURI, qualifiedName)</code>    </li>
<li><code>setAttributeNode(np, newAttr)</code>    </li>
<li><code>removeAttributeNode(np, oldAttr)</code>    </li>
<li><code>getElementsByTagNameNS(np, namespaceURI, qualifiedName)</code>    </li>
<li><code>hasAttribute(np, name)</code>    </li>
<li><code>hasAttributeNS(np, namespaceURI, qualifiedName)</code>  </li>
</ul>

<p>Text: <br />
<code>type(Node), pointer</code></p>

<ul>
<li><code>splitText(np, offset)</code>    </li>
</ul>

<p>DocumentType: <br />
<code>type(Node), pointer</code></p>

<ul>
<li><code>getName(np)</code>    </li>
<li><code>getEntites(np)</code>    </li>
<li><code>getNotations(np)</code>    </li>
<li><code>getPublicId(np)</code>    </li>
<li><code>getSystemId(np)</code>    </li>
<li><code>getInternalSubset(np)</code>    </li>
</ul>

<p>Notation: <br />
<code>type(Node), pointer</code> </p>

<ul>
<li><code>getPublicId(np)</code>    </li>
<li><code>getSystemId(np)</code>    </li>
</ul>

<p>Entity: <br />
<code>type(Node), pointer</code></p>

<ul>
<li><code>getPublicId(np)</code>    </li>
<li><code>getSystemId(np)</code>  </li>
<li><code>getNotationName(np)</code>    </li>
</ul>

<p>ProcessingInstruction: <br />
<code>type(Node), pointer</code></p>

<ul>
<li><code>getTarget(np)</code>    </li>
<li><code>getData(np)</code>    </li>
<li><code>setData(np, data)</code> </li>
</ul>

<p>In addition, the following DOM Core Level 3 functions are available:</p>

<p>Document:</p>

<ul>
<li><code>getDocumentURI(np)</code>  </li>
<li><code>setDocumentURI(np, documentURI)</code>  </li>
<li><code>getDomConfig(np)</code>  </li>
<li><code>getInputEncoding(np)</code>  </li>
<li><code>getStrictErrorChecking(np)</code>  </li>
<li><code>setStrictErrorChecking(np, strictErrorChecking)</code>  </li>
<li><code>getXmlEncoding(np)</code>  </li>
<li><code>getXmlStandalone(np)</code>  </li>
<li><code>setXmlStandalone(np, xmlStandalone)</code>  </li>
<li><code>getXmlVersion(np)</code>  </li>
<li><code>setXmlVersion(np, xmlVersion)</code>  </li>
<li><code>adoptNode(np, source)</code>   </li>
<li><code>normalizeDocument(np)</code>  </li>
<li><code>renameNode(np, namespaceURI, qualifiedName)</code>  </li>
</ul>

<p>Node:</p>

<ul>
<li><code>getBaseURI(np)</code>  </li>
<li><code>getTextContent(np)</code>  </li>
<li><code>setTextContent(np, textContent)</code>  </li>
<li><code>isEqualNode(np, other)</code></li>
<li><code>isSameNode(np)</code>  </li>
<li><code>isDefaultNamespace(np, namespaceURI)</code>  </li>
<li><code>lookupPrefix(np, namespaceURI)</code>  </li>
<li><code>lookupNamespaceURI(np, prefix)</code>  </li>
</ul>

<p>Attr:</p>

<ul>
<li><code>getIsId(np)</code></li>
</ul>

<p>Entity:  </p>

<ul>
<li><code>getInputEncoding(np)</code>  </li>
<li><code>getXmlVersion(np)</code>  </li>
<li><code>getXmlEncoding(np)</code>  </li>
</ul>

<p>Text:</p>

<ul>
<li><code>getIsElementContentWhitespace(np)</code>  </li>
</ul>

<p>DOMConfiguration: <br />
<code>type(DOMConfiguration)</code></p>

<ul>
<li><code>canSetParameter(arg, name, value)</code>  </li>
<li><code>getParameter(arg, name)</code> </li>
<li><code>getParameterNames(arg)</code>  </li>
<li><code>setParameter(arg, name)</code>  </li>
</ul>

<p><em>NB For details on DOMConfiguration, see <a href="#DomConfiguration">below</a></em></p>

<h3>Object Model</h3>

<p>The DOM is written in terms of an object model involving inheritance, but also permits a flattened model. FoX implements this flattened model - all objects descending from the Node are of the opaque type <code>Node</code>. Nodes carry their own type, and attempts to call functions defined on the wrong nodetype (for example, getting the <code>target</code> of a node which is not a PI) will result in a <code>FoX_INVALID_NODE</code> exception.</p>

<p>The other types available through the FoX DOM are:</p>

<ul>
<li><code>DOMConfiguration</code>  </li>
<li><code>DOMException</code>   </li>
<li><code>DOMImplementation</code>  </li>
<li><code>NodeList</code>  </li>
<li><code>NamedNodeMap</code></li>
</ul>

<h3>FoX DOM and pointers</h3>

<p>All DOM objects exposed to the user may only be manipulated through pointers. Attempts to access them directly will result in compile-time or run-time failures according to your environment.</p>

<p>This should have little effect on the structure of your programs, except that you must always remember, when calling a DOM function, to perform pointer assignment, not direct assignment, thus: <br />
<code>child =&gt; getFirstChild(parent)</code> <br />
and <em>not</em> <br />
<code>child = getFirstChild(parent)</code>  </p>

<h3>Memory handling</h3>

<p>Fortran offers no garbage collection facility, so unfortunately a small degree of memory
handling is necessarily exposed to the user.</p>

<p>However, this has been kept to a minimum. FoX keeps track of all memory allocated and used when calling DOM routines, and keeps references to all DOM objects created.</p>

<p>The only memory handling that the user needs to take care of is destroying any
DOM Documents (whether created manually, or by the <code>parse()</code> routine.) All other nodes or node structures created will be destroyed automatically by the relevant <code>destroy()</code> call.</p>

<p>As a consequence of this, all DOM objects which are part of a given document will become inaccessible after the document object is destroyed.</p>

<h2>Additional functions.</h2>

<p><a name="DomUtilityFunctions"/></p>

<p>Several additional utility functions are provided by FoX.</p>

<h3>Input and output of XML data</h3>

<p>Firstly, to construct a DOM tree, from either a file or a string containing XML data.</p>

<ul>
<li><code>parseFile</code> <br />
<strong>filename</strong>: <em>string</em> <br />
(<strong>configuration</strong>): <em>DOMConfiguration</em> <br />
(<strong>ex</strong>): <em>DOMException</em>  </li>
</ul>

<p><strong>filename</strong> should be an XML document. It will be opened and parsed into a DOM tree. The parsing is performed by the FoX SAX parser; if the XML document is not well-formed, a <code>PARSE_ERR</code> exception will be raised. <strong>configuration</strong> is an optional argument - see <a href="#DomConfiguration">DOMConfiguration</a> for its meaning.</p>

<ul>
<li><code>parseString</code> <br />
<strong>XMLstring</strong>: <em>string</em> <br />
(<strong>configuration</strong>): <em>DOMConfiguration</em> <br />
(<strong>ex</strong>): <em>DOMException</em></li>
</ul>

<p><strong>XMLstring</strong> should be a string containing XML data. It will be parsed into a DOM tree. The parsing is performed by the FoX SAX parser; if the XML document is not well-formed, a <code>PARSE_ERR</code> exception will be raised. <strong>configuration</strong> is an optional argument - see <a href="#DomConfiguration">DOMConfiguration</a> for its meaning.</p>

<p>Both <code>parseFile</code> and <code>parseString</code> return a pointer to a <code>Node</code> object containing the Document Node.`</p>

<p>Secondly, to output an XML document:</p>

<ul>
<li><code>serialize</code> <br />
<strong>arg</strong>: <em>Node, pointer</em>
<strong>fileName</strong>: <em>string</em> </li>
</ul>

<p>This will open <code>fileName</code> and serialize the DOM tree by writing into the file. If <code>fileName</code> already exists, it will be overwritten. If an problem arises in serializing the document, then a fatal error will result.</p>

<p>(Control over serialization options is done through the configuration of the <strong>arg</strong>'s ownerDocument, see <a href="#DomConfiguration">below</a>.)</p>

<p>Finally, to clean up all memory associated with the DOM, it is necessary to call:</p>

<ul>
<li><code>destroy</code> <br />
<strong>np</strong>: <em>Node, pointer</em></li>
</ul>

<p>This will clear up all memory usage associated with the document (or documentType) node passed in.</p>

<h3>Extraction of data from an XML file.</h3>

<p><a name="dataExtraction"/></p>

<p>The standard DOM functions only deal with string data. When dealing with numerical (or logical) data,
the following functions may be of use.</p>

<ul>
<li><code>extractDataContent</code>  </li>
<li><code>extractDataAttribute</code>  </li>
<li><code>extractDataAttributeNS</code></li>
</ul>

<p>These extract data from, respectively, the text content of an element, from one of its attributes, or from one of its namespaced attributes.
They are used like so:</p>

<p>(where <code>p</code> is an element which has been selected by means of the other DOM functions)</p>

<pre><code>call extractDataContent(p, data)
</code></pre>

<p>The subroutine will look at the text contents of the element, and interpret according to the type of <code>data</code>. That is, if <code>data</code> has been declared as an <code>integer</code>, then the contents of <code>p</code> will be read as such an placed into <code>data</code>.</p>

<p><code>data</code> may be a <code>string</code>, <code>logical</code>, <code>integer</code>, <code>real</code>, <code>double precision</code>, <code>complex</code> or <code>double complex</code> variable.</p>

<p>In addition, if <code>data</code> is supplied as a rank-1 or rank-2 variable (ie an array or a matrix) then the data will be read in assuming it to be a space- or comma-separated list of such data items.</p>

<p>Thus, the array of integers within the XML document:</p>

<pre><code>&lt;element&gt; 1 2 3 4 5 6 &lt;/element&gt;
</code></pre>

<p>could be extracted by the following Fortran program:</p>

<pre><code>type(Node), pointer :: doc, p
integer :: i_array(6)

doc =&gt; parseFile(filename)
p =&gt; item(getElementsByTagName(doc, "element"), 0)
call extractDataContent(p, i_array)
</code></pre>

<h4>Contents and Attributes</h4>

<p>For extracting data from text content, the example above suffices. For data in a non-namespaced attribute (in this case, a 2x2 matrix of real numbers)</p>

<pre><code>&lt;element att="0.1, 2.3 7.56e23, 93"&gt; Some uninteresting text &lt;/element&gt;
</code></pre>

<p>then use a Fortran program like:</p>

<pre><code>type(Node), pointer :: doc, p
real :: r_matrix(2,2)

doc =&gt; parseFile(filename)
p =&gt; item(getElementsByTagName(doc, "element"), 0)
call extractDataAttribute(p, "att", r_matrix)
</code></pre>

<p>or for extracting from a namespaced attribute (in this case, a length-2 array of complex numbers):</p>

<pre><code>&lt;myml xmlns:ns="http://www.example.org"&gt;
  &lt;element ns:att="0.1,2.3  3.4e2,5.34"&gt; Some uninteresting text &lt;/element&gt;
&lt;/myml&gt;
</code></pre>

<p>then use a Fortran program like:</p>

<pre><code>type(Node), pointer :: doc, p
complex :: c_array(2)

doc =&gt; parseFile(filename)
p =&gt; item(getElementsByTagName(doc, "element"), 0)
call extractDataAttributeNS(p, &amp;
     namespaceURI="http://www.example.org", localName="att", &amp;
     data=c_array)
</code></pre>

<h4>Error handling</h4>

<p>The extraction may fail of course, if the data is not of the sort specified, or if there are not enough elements to fill the array or matrix. In such a case, this can be detected by the optional arguments <code>num</code> and <code>iostat</code>. </p>

<p><code>num</code> will hold the number of items successfully read. Hopefully this should be equal to the expected number of items; but it may be less if reading failed for some reason, or if there were less items than expected in the element.</p>

<p><code>iostat</code> will hold an integer - this will be <code>0</code> if the extraction went ok; <code>-1</code> if too few elements were found, <code>1</code> if although the read went ok, there were still some elements left over, or <code>2</code> if the extraction failed due to either a badly formatted number, or due to the wrong data type being found.</p>

<h4>String arrays</h4>

<p>For all data types apart from strings, arrays and matrices are specified by space- or comma-separated lists. For strings, some additional options are available. By default, arrays will be extracted assuming that separators are spaces (and multiple spaces are ignored). So:</p>

<pre><code>&lt;element&gt; one two     three &lt;/element&gt;
</code></pre>

<p>will result in the string array <code>(/"one", "two", "three"/)</code>.</p>

<p>However, you may specify an optional argument <code>separator</code>, which specifies another single-character separator to use (and does not ignore multiple spaces). So:</p>

<pre><code>&lt;element&gt;one, two, three &lt;/element&gt;
</code></pre>

<p>will result in the string array <code>(/"one", " two", " three "/)</code>. (note the leading and trailing spaces).</p>

<p>Finally, you can also specify an optional logical argument, <code>csv</code>. In this case, the <code>separator</code> is ignored, and the extraction proceeds assuming that the data is a list of comma-separated values. (see: <a href="http://en.wikipedia.org/wiki/Comma-separated_values">CSV</a>)</p>

<h3>Other utility functions</h3>

<ul>
<li><code>setFoX_checks</code> <br />
<strong>FoX_checks</strong>: <em>logical</em></li>
</ul>

<p>This affects whether additional FoX-only checks are made (see <a href="#DomException">DomExceptions</a> below). </p>

<ul>
<li><code>getFoX_checks</code> <br />
<strong>arg</strong>: <em>DOMImplementation, pointer</em>  </li>
</ul>

<p>Retrieves the current setting of FoX_checks.</p>

<p>Note that FoX_checks can only be turned on and off globally, not on a per-document basis.</p>

<ul>
<li><code>setLiveNodeLists</code> <br />
<strong>arg</strong>: <em>Node, pointer</em> <br />
<strong>liveNodeLists</strong>: <em>logical</em></li>
</ul>

<p><strong>arg</strong> must be a Document Node. Calling this function affects whether any nodelists active on the document are treated as live - ie whether updates to the documents are reflected in the contents of nodelists (see <a href="#DomLiveNodelists">DomLiveNodelists</a> below).</p>

<ul>
<li><code>getLiveNodeLists</code> <br />
<strong>arg</strong>: <em>Node, pointer</em></li>
</ul>

<p>Retrieves the current setting of liveNodeLists.</p>

<p>Note that the live-ness of nodelists is a per-document setting.</p>

<h3>Exception handling</h3>

<p><a name="DomException"/></p>

<p>Exception handling is important to the DOM. The W3C DOM standards provide not only interfaces to the DOM, but also specify the error handling that should take place when invalid calls are made.</p>

<p>The DOM specifies these in terms of a <code>DOMException</code> object, which carries a numeric code whose value reports the kind of error generated. Depending upon the features available in a particular computer language, this DOMException object should be generated and thrown, to be caught by the end-user application.</p>

<p>Fortran of course has no mechanism for throwing and catching exceptions. However, the behaviour of an exception can be modelled using Fortran features.</p>

<p>FoX defines an opaque <code>DOMException</code> object.
Every DOM subroutine and function implemented by FoX will take an optional argument, 'ex', of type <code>DOMException</code>. </p>

<p>If the optional argument is not supplied, any errors within the DOM will cause an immediate abort, with a suitable error message. However, if the optional argument <em>is</em> supplied, then the error will be captured within the <code>DOMException</code> object, and returned to the caller for inspection. It is then up to the application to decide how to proceed.</p>

<p>Functions for inspecting and manipulating the <code>DOMException</code> object are described below:</p>

<ul>
<li><code>inException</code>: <br />
<strong>ex</strong>: <em>DOMException</em></li>
</ul>

<p>A function returning a logical value, according to whether <code>ex</code> is in exception - that is, whether the last DOM function or subroutine, from which <code>ex</code> returned, caused an error. Note that this will not change the status of the exception.</p>

<ul>
<li><code>getExceptionCode</code> <br />
<strong>ex</strong>: <em>DOMException</em></li>
</ul>

<p>A function returning an integer value, describing the nature of the exception reported in <code>ex</code>. If the integer is 0, then <code>ex</code> does not hold an exception. If the integer is less than 200, then the error encountered was of a type specified by the DOM standard; for a full list, see below, and for explanations, see the various DOM standards. If the integer is 200 or greater, then the code represents a FoX-specific error. See the list below.</p>

<p>Note that calling <code>getExceptionCode</code> will clean up all memory associated with the DOMException object, and reset the object such that it is no longer in exception.</p>

<h4>Exception handling and memory usage.</h4>

<p>Note that when an Exception is thrown, memory is allocated within the DOMException object. Calling <code>getExceptionCode</code> on a DOMEXception will clean up this memory. If you use the exception-handling interfaces of FoX, then you must check every exception, and ensure you check its code, otherwise your program will leak memory.</p>

<h4>FoX exceptions.</h4>

<p>The W3C DOM interface allows the creation of unserializable XML document in various ways. For example, it permits characters to be added to a text node which would be invalid XML. FoX performs multiple additional checks on all DOM calls to prevent the creation of unserializable trees. These are reported through the DOMException mechanisms noted above, using additional exception codes. However, if for some reason, you want to create such trees, then it is possible to switch off all FoX-only checks. (DOM-mandated checks may not be disabled.) To do this, use the <code>setFoX_checks</code> function described in <a href="#DomUtilityFunctions">DomUtilityFunctions</a>.</p>

<p>Note that FoX does not yet currently check for all ways that a tree may be made non-serializable.</p>

<h4>List of exceptions.</h4>

<p>The following is the list of all exception codes (both specified in the W3C DOM and those related to FoX-only checks) that can be generated by FoX:</p>

<ul>
<li>INDEX_SIZE_ERR = 1</li>
<li>DOMSTRING_SIZE_ERR = 2</li>
<li>HIERARCHY_REQUEST_ERR = 3</li>
<li>WRONG_DOCUMENT_ERR = 4</li>
<li>INVALID_CHARACTER_ERR = 5</li>
<li>NO_DATA_ALLOWED_ERR = 6</li>
<li>NO_MODIFICATION_ALLOWED_ERR = 7</li>
<li>NOT_FOUND_ERR = 8</li>
<li>NOT_SUPPORTED_ERR = 9</li>
<li>INUSE_ATTRIBUTE_ERR = 10</li>
<li>INVALID_STATE_ERR = 11</li>
<li>SYNTAX_ERR = 12</li>
<li>INVALID_MODIFICATION_ERR = 13</li>
<li>NAMESPACE_ERR = 14</li>
<li>INVALID_ACCESS_ERR = 15</li>
<li>VALIDATION_ERR = 16</li>
<li>TYPE_MISMATCH_ERR = 17</li>
<li>INVALID_EXPRESSION_ERR = 51</li>
<li>TYPE_ERR = 52</li>
<li>PARSE_ERR = 81</li>
<li>SERIALIZE_ERR = 82</li>
<li>FoX_INVALID_NODE = 201</li>
<li>FoX_INVALID_CHARACTER = 202</li>
<li>FoX_NO_SUCH_ENTITY = 203</li>
<li>FoX_INVALID_PI_DATA = 204</li>
<li>FoX_INVALID_CDATA_SECTION = 205</li>
<li>FoX_HIERARCHY_REQUEST_ERR = 206</li>
<li>FoX_INVALID_PUBLIC_ID = 207</li>
<li>FoX_INVALID_SYSTEM_ID = 208</li>
<li>FoX_INVALID_COMMENT = 209</li>
<li>FoX_NODE_IS_NULL = 210</li>
<li>FoX_INVALID_ENTITY = 211</li>
<li>FoX_INVALID_URI = 212</li>
<li>FoX_IMPL_IS_NULL = 213</li>
<li>FoX_MAP_IS_NULL = 214</li>
<li>FoX_LIST_IS_NULL = 215</li>
<li>FoX_INTERNAL_ERROR = 999</li>
</ul>

<h3>Live nodelists</h3>

<p><a name="DomLiveNodelists"/></p>

<p>The DOM specification requires that all NodeList objects are <em>live</em> - that is, that any change in the document structure is immediately reflected in the contents of any nodelists.</p>

<p>For example, any nodelists returned by getElementsByTagName or getElementsByTagNameNS must be updated whenever nodes are added to or removed from the document; and the order of nodes in the nodelists must be changed if the document structure changes.</p>

<p>Though FoX does keep all nodelists live, this can impose a significant performance penalty when manipulating large documents. Therefore, FoX can be instructed to inly use 'dead' nodelists - that is, nodelists which reflect a snapshot of the document structure at the point they were created. To do this, call <code>setLiveNodeLists</code> (see API documentation).</p>

<p>However, note that the nodes within the nodelist remain live - any changes made to the nodes will be reflected in accessing them through the nodelist.</p>

<p>Furthermore, since the nodelists are still associated with the document, they and their contents will be rendered inaccessible when the document is destroyed.</p>

<h2>DOM Configuration</h2>

<p><a name="DomConfiguration"/></p>

<p>Multiple valid DOM trees may be produced from a single document. When parsing input, some of these choices are made available to the user.</p>

<p>By default, the DOM tree presented to the user will be produced according to the following criteria:</p>

<ul>
<li>there will be no adjacent text nodes  </li>
<li>Cdata nodes will appear as such in the DOM tree  </li>
<li>EntityReference nodes will appear in the DOM tree.</li>
</ul>

<p>However, if another tree is desired, the user may change this. For example, very often you would rather be working with the fully canonicalized tree, with all cdata sections replaced by text nodes and merged, and all entity references replaced with their contents.</p>

<p>The mechanism for doing this is the optional <code>configuration</code> argument to <code>parseFile</code> and <code>parseString</code>. <code>configuration</code> is a <code>DOMConfiguration</code> object, which may be manipulated by <code>setParameter</code> calls.</p>

<p>Note that FoX's implementation of <code>DOMConfiguration</code> does not follow the specification precisely. One <code>DOMConfiguration</code> object controls all of parsing, normalization and serialization. It can be used like so:</p>

<pre><code>use FoX_dom
implicit none
type(Node), pointer :: doc
! Declare a new configuration object
type(DOMConfiguration), pointer :: config
! Request full canonicalization
! ie convert CDATA sections to text sections, remove all entity references etc.
config =&gt; newDOMConfig()
call setParameter(config, "canonical-form", .true.)
! Turn on validation
call setParameter(config, "validate", .true.)
! parse the document
doc =&gt; parseFile("doc.xml", config)

! Do a whole lot of DOM processing ...

! change the configuration to allow cdata-sections to be preserved.
call setParameter(getDomConfig(doc), "cdata-sections", .true.)
! normalize the document again 
call normalizeDocument(doc)
! change the configuration to influence the output - make sure there is an XML declaration
call setParameter(getDomConfig(doc), "xml-declaration", .true.)
! and write the document out.
call serialize(doc)
! once everything is done, destroy the doc and config
call destroy(doc)
call destroy(config)
</code></pre>

<p>The available configuration options are fully explained in:</p>

<ul>
<li><a href="http://www.w3.org/TR/DOM-Level-3-Core/core.html#DOMConfiguration">DOM Core 3</a>  </li>
<li><a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/load-save.html#LS-LSParser">DOM Core LSParser</a>  </li>
<li><a href="http://www.w3.org/TR/2004/REC-DOM-Level-3-LS-20040407/load-save.html#LS-LSSerializer">DOM Core LSSerializer</a>  </li>
</ul>

<p>and are all implemented, with the exceptions of: <code>error-handler</code>, <code>schema-location</code>, and <code>schema-type</code>. <br />
In total there are 24 implemented configuration options (<code>schema-location</code> and <code>schema-type</code> are not
implemented). The options known by FoX are as follows:</p>

<ul>
<li><code>canonical-form</code> default: false, can be set to true. See note below.</li>
<li><code>cdata-sections</code> default: true, can be changed.</li>
<li><code>check-character-normalization</code> default: false, cannot be changed.</li>
<li><code>comments</code> default: true, can be changed.</li>
<li><code>datatype-normalization</code> default: false, cannot be changed.</li>
<li><code>element-content-whitespace</code> default: true, can be changed.</li>
<li><code>entities</code> default: true, can be changed.</li>
<li><code>error-handler</code> default: false, cannot be changed. This is a breach of the DOM specification.</li>
<li><code>namespaces</code> default: true, can be changed.</li>
<li><code>namespace-declarations</code> default: true, can be changed.</li>
<li><code>normalize-characters</code> default: false, cannot be changed.</li>
<li><code>split-cdata-sections</code> default: true, can be changed.</li>
<li><code>validate</code> default: false, can be changed. See note below.</li>
<li><code>validate-if-schema</code> default: false, can be changed.</li>
<li><code>well-formed</code> default true, cannot be changed.</li>
<li><code>charset-overrides-xml-encoding</code> default false, cannot be changed.</li>
<li><code>disallow-doctype</code> default false, cannot be changed.</li>
<li><code>ignore-unknown-character-denormalizations</code> default true, cannot be changed.</li>
<li><code>resource-resolver</code> default false, cannot be changed.</li>
<li><code>supported-media-types-only</code> default false, cannot be changed.</li>
<li><code>discard-default-content</code> default: true, can be changed.</li>
<li><code>format-pretty-print</code> default: false, cannot be changed.</li>
<li><code>xml-declaration</code> default: true, can be changed.</li>
<li><code>invalid-pretty-print</code> default: false, can be changed. This is a FoX specific extension which works like <code>format-pretty-print</code> but does not preseve the validity of the document.</li>
</ul>

<p>Setting <code>canonical-form</code> changes the value of <code>entities</code>, <code>cdata-sections</code>, <code>discard-default-content</code>, <code>invalid-pretty-print</code>, and <code>xml-declaration</code>to false and changes <code>namespaces</code>, <code>namespace-declarations</code>, and <code>element-content-whitespace</code> to true. Unsetting <code>canonical-form</code> causes these options to revert to the defalt settings. Changing the values of any of these options has the side effect of unsetting <code>canonical-form</code> (but does not cause the other options to be reset). Setting <code>validate</code> unsets <code>validate-if-schema</code> and vica versa.</p>

<h2>DOM Miscellanea</h2>

<p><a name="DomMiscellanea"/></p>

<p>Other issues</p>

<ul>
<li>As mentioned in the documentation for WXML, it is impossible within Fortran to reliably output lines longer than 1024 characters. While text nodes containing such lines may be created in the DOM, on serialization newlines will be inserted as described in the documentation for WXML.</li>
<li>All caveats with regard to the FoX SAX processor apply to reading documents through the DOM interface. In particular, note that documents containing characters beyond the US-ASCII set will not be readable.</li>
</ul>

<p>It was decided to implement W3C DOM interfaces primarily because they are specified in a language-agnostic fashion, and thus made Fortran implementation possible. A number of criticisms have been levelled at the W3C DOM, but many apply only from the perspective of Java developers. However, more importantly, the W3C DOM suffers from a lack of sufficient error checking so it is very easy to create a DOM tree, or manipulate an existing DOM tree into a state, that cannot be serialized into a legal XML document.</p>

<p>(Although the Level 3 DOM specifications finally addressed this issue, they did so in a fashion that was neither very useful, nor easily translatable into a Fortran API.)</p>

<p>Therefore, FoX will by default produce errors about many attempts to manipulate the DOM in such a way as would result in invalid XML. These errors can be switched off if standards-compliant behaviour is wanted. Although extensive, these checks are not complete.
In particular, the way the W3C DOM mandates namespace handling makes it trivial to produce namespace non-well-formed document trees, and very difficult for the processor to automatically detect the non-well-formedness. Thus a fully well-formed tree is only guaranteed after a suitable <code>normalizeDocument</code> call.</p>
</div><hr/><div class="DoX">
<a name="FoX_utils"/>
<h1>UTILS</h1>

<p><code>FoX_utils</code> is a collection of general utility functions that the rest of FoX depends on, but which may be of independent use. They are documented here.</p>

<p>All functions are accessible from the <code>FoX_utils</code> module. </p>

<p>NB Unlike the APIs of WXML, WCML, and SAX, the UTILS APIs may not remain constant between FoX versions. While some effort will be expended to ensure they don't change unnecessarily, no guarantees are made.</p>

<p>For any end-users interested in the code who are worried about interface changes, it is recommended that the  relevant code (all found in the <code>utils/</code> directory be lifted directly and imported into other projects, rather than accessed through the FoX interfaces.</p>

<p>Two sets of utility functions are provided; one concerned with <a href="#UUID">UUID</a>s, and a set concerned with <a href="#URI">URI</a>s.</p>

<p><a name="UUID"/></p>

<h2>UUID</h2>

<p>UUIDs (see <a href="http://tools.ietf.org/html/rfc4122">RFC 4122</a>) are  Universally Unique IDentifiers. They are a 128-bit number, represented as a 36-character string. For example:</p>

<pre><code> f81d4fae-7dec-11d0-a765-00a0c91e6bf6
</code></pre>

<p>The intention of UUIDs is to enable distributed systems to uniquely identify information without significant central coordination. Thus, anyone can create a UUID and use it to identify something with reasonable confidence that the identifier will never be unintentionally used by anyone for anything else.</p>

<p>This property also makes them useful as Uniform Resource Names, to refer to a given document without requiring a position in a particular URI scheme. Thus the above UUID could be referred to as</p>

<pre><code>urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6
</code></pre>

<p>UUIDs are used by WCML to ensure that every document generated has a unique ID. This enables users to go back later on and have confidence that they are examining the same document, regardless of where it might have ended up in file-system hierarchies or databases.</p>

<p>In addition, UUIDs come in several flavours, one of which stores the time of creation to 100-nanosecond accuracy. This can later be extracted (see, for example <a href="http://www.famkruithof.net/uuid/uuidgen?typeReq=-1">this service</a>) to verify creation time.</p>

<p>This may well be useful for other XML document types, or indeed in non-XML applications. Thus, UUIDs may be generated by the following function, with one optional argument.</p>

<ul>
<li><code>generate_UUID</code> <br />
<strong>version</strong>: <em>integer</em></li>
</ul>

<p>This function returns a 36-character string containing the UUID.</p>

<p><strong>version</strong> identifies the version of UUID to be used (see section 4.1.3 of the RFC). Only versions 0, 1, and 4 are supported. Version 0 generates a nil UUID; version 1 a time-based UUID, and version 4 a pseudo-randomly-generated UUID.</p>

<p>Version 1 is the default, and is recommended.</p>

<p>(Note: all pseudo-random-numbers are generated using the high-quality Mersenne Twister algorithm, using the Fortran implementation of <a href="http://www.coyotegulch.com">Scott Robert Ladd</a>.)</p>

<p><a name="URI"/></p>

<h2>URI</h2>

<p>URIs (see <a href="http://tools.ietf.org/html/rfc2396">RFC 2396</a>) are  Universal Resource Identifiers. A URI is a string, containing several components, which identifies a resource. Very often, this resource is a file, and the URI represents the local or network path to this file.</p>

<p>For example:</p>

<pre><code>http://www.uszla.me.uk/FoX/DoX/index.html
</code></pre>

<p>is a URI pointing to the FoX documentation.</p>

<p>Equally, however:</p>

<pre><code>FoX/configure
</code></pre>

<p>is a URI reference pointing to the FoX configure script (relative to the current directory, or <code>base URI</code>).</p>

<p>A string which is a URI reference contains several components, some of which are optional.</p>

<ul>
<li><code>scheme</code> - eg, <code>http</code></li>
<li><code>authority</code> - eg, <code>www.uszla.me.uk</code></li>
<li><code>path</code> - eg, <code>/FoX/DoX/index.html</code></li>
</ul>

<p>In addition, a URI reference may contain <code>userinfo</code>, <code>host</code>, <code>port</code>, <code>query</code>, and <code>fragment</code> information. (see the <a href="http://tools.ietf.org/html/rfc2396">RFC</a> for full details.)</p>

<p>The FoX URI library provides the following features:</p>

<ul>
<li><p><code>type(URI)</code>
This is an opaque Fortran type which is used to hold URI information. The functions described below use this type.</p></li>
<li><p><code>parseURI</code>
This takes one argument, a URI reference, and returns a pointer to a newly-allocated URI object.</p></li>
</ul>

<p>If the string provided is not a valid URI reference, then a null pointer is returned; thus this function can be used to check whether a URI is valid.</p>

<ul>
<li><p><code>expressURI</code>
This takes one argument, a URI object, and returns the (fully-escaped) string representing that URI.</p></li>
<li><p><code>rebaseURI</code>
This takes two arguments, both URI objects, and returns a pointer to a third URI object. It calculates the location of the second URI with reference to the first.</p></li>
</ul>

<p>Thus, if the first URI were <code>/FoX/DoX</code>, and the second <code>../DoX2/index.html</code>, then the resulting URI would be <code>/FoX/DoX2/index.html</code></p>

<ul>
<li><code>destroyURI</code>
This takes one argument, a pointer to a URI object, and clears up all memory associated with it.</li>
</ul>

<p>For each component a URI might have (<code>scheme</code>, <code>authority</code>, <code>userinfo</code>, <code>host</code>, <code>port</code>, <code>path</code>, <code>query</code>, <code>fragment</code>) there are two functions for extracting the component:</p>

<ul>
<li><p><code>hasXXX</code> will return a logical variable according to whether the component is defined. (except for <code>path</code> which is always defined, but may be empty)</p></li>
<li><p><code>getXXX</code> will return a string containing the value of the component. (except for <code>port</code> which is returned as an integer.</p></li>
</ul>

<p>Thus, listing these functions in full:</p>

<ul>
<li><p><code>hasScheme</code>
Is there a scheme associated with the URI?</p></li>
<li><p><code>getScheme</code>
Return the value of the scheme</p></li>
<li><p><code>hasAuthority</code>
Is there an authority associated with the URI?</p></li>
<li><p><code>getAuthority</code>
Return the value of the authority</p></li>
<li><p><code>hasUserinfo</code>
Is there userinfo associated with the URI?</p></li>
<li><p><code>getUserinfo</code>
Return the value of the userinfo</p></li>
<li><p><code>hasHost</code>
Is there a host associated with the URI?</p></li>
<li><p><code>getHost</code>
Return the value of the host</p></li>
<li><p><code>hasPort</code>
Is there a port associated with the URI?</p></li>
<li><p><code>getPort</code>
Return the value of the port</p></li>
<li><p><code>getPath</code>
Return the value of the path</p></li>
<li><p><code>hasQuery</code>
Is there a query associated with the URI?</p></li>
<li><p><code>getQuery</code>
Return the value of the query</p></li>
<li><p><code>hasFragment</code>
Is there a fragment associated with the URI?</p></li>
<li><p><code>getFragment</code>
Return the value of the fragment</p></li>
</ul>
</div><hr/><div class="DoX">
<a name="Information"/>
<h1>Further information</h1>

<p>FoX evolved from the initial codebase of <a href="http://lcdx00.wm.lc.ehu.es/ag/xml/">xmlf90</a>,
which was written largely by Alberto Garcia &lt;<a href="&#109;&#x61;&#105;&#108;t&#111;:&#97;&#108;&#98;&#x65;&#114;&#x74;&#x6F;&#103;&#64;i&#99;&#109;&#x61;&#x62;.&#101;&#115;">&#97;&#108;&#98;&#x65;&#114;&#x74;&#x6F;&#103;&#64;i&#99;&#109;&#x61;&#x62;.&#101;&#115;</a>> and Jon Wakelin &lt;<a href="&#x6D;&#97;&#105;&#108;&#116;&#x6F;:&#106;&#x6F;&#110;&#x2E;&#119;a&#x6B;&#101;&#x6C;&#105;&#110;&#64;&#98;&#x72;&#x69;&#x73;t&#x6F;&#108;&#46;&#x61;&#x63;&#46;&#117;&#107;">&#106;&#x6F;&#110;&#x2E;&#119;a&#x6B;&#101;&#x6C;&#105;&#110;&#64;&#98;&#x72;&#x69;&#x73;t&#x6F;&#108;&#46;&#x61;&#x63;&#46;&#117;&#107;</a>>.</p>

<p>FoX is the work of Toby White &lt;<a href="&#x6D;&#x61;&#x69;&#x6C;&#x74;&#111;:&#116;&#111;&#119;&#64;&#x75;&#115;&#122;&#108;&#97;.&#x6D;&#101;&#46;&#x75;&#107;">&#116;&#111;&#119;&#64;&#x75;&#115;&#122;&#108;&#97;.&#x6D;&#101;&#46;&#x75;&#107;</a>>, and all bug reports/complaints/bouquets of roses should be sent to him. Andrew Walker &lt;<a href="&#x6D;&#x61;&#105;l&#116;&#111;:&#97;&#110;&#x64;&#114;&#x65;w&#x2E;&#x77;&#x61;lk&#x65;&#x72;&#64;&#x62;&#114;&#105;&#115;&#x74;o&#x6C;&#x2E;&#x61;c.&#117;&#x6B;">&#97;&#110;&#x64;&#114;&#x65;w&#x2E;&#x77;&#x61;lk&#x65;&#x72;&#64;&#x62;&#114;&#105;&#115;&#x74;o&#x6C;&#x2E;&#x61;c.&#117;&#x6B;</a>> currently looks after maintenance of FoX.</p>

<p>There is a FoX website at <a href="http://www1.gly.bris.ac.uk/~walker/FoX/">http://www1.gly.bris.ac.uk/~walker/FoX/</a>.</p>

<p>There is also a mailing list for announcements/queries/bug reports. Information on how to subscribe may be found at <a href="http://groups.google.com/group/fox-discuss/">http://groups.google.com/group/fox-discuss/</a>. The archive of an older mailing list can be found at <a href="http://www.uszla.me.uk/pipermail/fox/">http://www.uszla.me.uk/pipermail/fox/</a>.</p>

<p>This manual is &copy; Toby White 2006-2008 with additional modifications by Andrew Walker 2008-2010.</p>
</div><hr/><div class="DoX">
<a name="Licensing"/>
<h1>Licensing</h1>

<p>FoX is licensed under the agreement below. This is intended to make it as freely available as possible, subject only to retaining copyright notices and acknowledgements.</p>

<p>If for any reason this license causes issues with your intended use of the code, please contect the author.</p>

<p>The license can also be found within the distributed source, in the file FoX/LICENSE</p>

<p>Copyright: <br />
&copy; 2003, 2004, Alberto Garcia, Jon Wakelin <br />
&copy; 2005-2008, Toby White <br />
&copy; 2007-2009, Gen-Tao Chiang
&copy; 2008-2012, Andrew Walker
All rights reserved.</p>

<p>Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions are
met:</p>

<ul>
<li><p>Redistributions of source code must retain the above copyright notice, 
this list of conditions and the following disclaimer.</p></li>
<li><p>Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.</p></li>
<li><p>Neither the name of the copyright holder nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.</p></li>
</ul>

<p>THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.</p>

<h3>Third-party code.</h3>

<p>In addition, FoX includes a random number library, written by <a href="http://www.coyotegulch.com">Scott Robert Ladd</a>, which is licensed as follows:</p>

<p>!  This computer program source file is supplied "AS IS". Scott Robert <br />
!  Ladd (hereinafter referred to as "Author") disclaims all warranties, <br />
!  expressed or implied, including, without limitation, the warranties <br />
!  of merchantability and of fitness for any purpose. The Author <br />
!  assumes no liability for direct, indirect, incidental, special, <br />
!  exemplary, or consequential damages, which may result from the use <br />
!  of this software, even if advised of the possibility of such damage. <br />
! <br />
!  The Author hereby grants anyone permission to use, copy, modify, and <br />
!  distribute this source code, or portions hereof, for any purpose, <br />
!  without fee, subject to the following restrictions: <br />
! <br />
!      1. The origin of this source code must not be misrepresented. <br />
! <br />
!      2. Altered versions must be plainly marked as such and must not <br />
!         be misrepresented as being the original source. <br />
! <br />
!      3. This Copyright notice may not be removed or altered from any <br />
!         source or altered source distribution. <br />
! <br />
!  The Author specifically permits (without fee) and encourages the use <br />
!  of this source code for entertainment, education, or decoration. If <br />
!  you use this source code in a product, acknowledgment is not required <br />
!  but would be appreciated.  </p>
</div><hr/><div class="DoX">
</div>
</body>
</html>
